Package 'affiner'

Description

Dilate, permute, project, reflect, rotate, shear, and translate 2D and 3D points. Supports parallel projections including oblique projections such as the cabinet projection as well as axonometric projections such as the isometric projection. Use 'grid's "affine transformation" feature to render illustrated flat surfaces.

Package options

The following affiner function arguments may be set globally via base::options():

affiner_angular_unit

The default for the unit argument used by angle() and as_angle(). The default for this option is "degrees".

affiner_grid_unit

The default for the unit argument used by affine_settings(). The default for this option is "inches".

The following cli options may also be of interest:

cli.unicode

Whether UTF-8 character support should be assumed. Along with l10n_info() used to determine the default of the use_unicode argument of format.angle() and print.angle().

Author(s)

Maintainer: Trevor L. Davis [email protected] (ORCID)

See Also

Useful links:

• https://trevorldavis.com/R/affiner/

• Report bugs at https://github.com/trevorld/affiner/issues

Description

abs() computes the Euclidean norm for Coord2D class objects and Coord3D class objects.

Usage

## S3 method for class 'Coord1D'
abs(x)

## S3 method for class 'Coord2D'
abs(x)

## S3 method for class 'Coord3D'
abs(x)

Arguments

Value

A numeric vector

Examples

z <- complex(real = 1:4, imaginary = 1:4)
  p <- as_coord2d(z)
  abs(p) # Euclidean norm
  # Less efficient ways to calculate same Euclidean norms
  sqrt(p * p) # `*` dot product
  distance2d(p, as_coord2d(0, 0, 0))

  # In {base} R `abs()` calculates Euclidean norm of complex numbers
  all.equal(abs(p), abs(z))
  all.equal(Mod(p), Mod(z))

  p3 <- as_coord3d(x = 1:4, y = 1:4, z = 1:4)
  abs(p3)

Description

affine_settings() computes grid group affine transformation feature viewport and transformation function settings given the (x,y) coordinates of the corners of the affine transformed "viewport" one wishes to draw in.

Usage

affine_settings(
  xy = data.frame(x = c(0, 0, 1, 1), y = c(1, 0, 0, 1)),
  unit = getOption("affiner_grid_unit", "inches")
)

Arguments

Value

A named list with the following group affine transformation feature viewport and functions settings:

transform

An affine transformation function to pass to affineGrob() or useGrob(). If getRversion() is less than "4.2.0" will instead be NULL.

vp

A grid::viewport() object to pass to affineGrob() or useGrob().

sx

x-axis sx factor

flipX

whether the affine transformed "viewport" is "flipped" horizontally

x

x-coordinate for viewport

y

y-coordinate for viewport

width

Width of viewport

height

Height of viewport

default.units

Default grid::unit() for viewport

angle

angle for viewport

Usage in other packages

To avoid taking a dependency on affiner you may copy the source of affine_settings() into your own package under the permissive Unlicense. Either use usethis::use_standalone("trevorld/affiner", "standalone-affine-settings.r") or copy the file standalone-affine-settings.r into your R directory and add grid to the Imports of your DESCRIPTION file.

See Also

Intended for use with affineGrob() and grid::useGrob(). See https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html for more information about the group affine transformation feature.

Examples

if (require("grid")) {
  grob <- grobTree(rectGrob(gp = gpar(fill = "blue", col = NA)),
                   circleGrob(gp=gpar(fill="yellow", col = NA)),
                   textGrob("RSTATS", gp=gpar(fontsize=32)))
  grid.newpage()
  pushViewport(viewport(width=unit(4, "in"), height=unit(2, "in")))
  grid.draw(grob)
  popViewport()
}
if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  vp_define <- viewport(width=unit(2, "in"), height=unit(2, "in"))
  settings <- affine_settings(xy = list(x = c(1/3, 0/3, 2/3, 3/3),
                                        y = c(2/3, 1/3, 1/3, 2/3)),
                              unit = "snpc")
  affine <- affineGrob(grob,
                       vp_define=vp_define,
                       transform = settings$transform,
                       vp_use = settings$vp)
  grid.newpage()
  grid.draw(affine)
}
if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  settings <- affine_settings(xy = list(x = c(3/3, 2/3, 0/3, 1/3),
                                        y = c(2/3, 1/3, 1/3, 2/3)),
                              unit = "snpc")
  affine <- affineGrob(grob,
                       vp_define=vp_define,
                       transform = settings$transform,
                       vp_use = settings$vp)
  grid.newpage()
  grid.draw(affine)
}

Description

affineGrob() is a grid grob function to facilitate using the group affine transformation features introduced in R 4.2.

Usage

affineGrob(
  grob,
  vp_define = NULL,
  transform = NULL,
  vp_use = NULL,
  name = NULL,
  gp = grid::gpar(),
  vp = NULL
)

grid.affine(...)

Arguments

Value

A grid::gTree() (grob) object of class "affine". As a side effect grid.affine() draws to the active graphics device.

See Also

See affine_settings() for computing good transform and vp_use settings. See https://www.stat.auckland.ac.nz/~paul/Reports/GraphicsEngine/groups/groups.html for more information about the group affine transformation feature. See isocubeGrob() which wraps this function to render isometric cubes.

Examples

if (require("grid")) {
  grob <- grobTree(rectGrob(gp = gpar(fill = "blue", col = NA)),
                   circleGrob(gp=gpar(fill="yellow", col = NA)),
                   textGrob("RSTATS", gp=gpar(fontsize=32)))
  grid.newpage()
  pushViewport(viewport(width=unit(4, "in"), height=unit(2, "in")))
  grid.draw(grob)
  popViewport()
}

if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  vp_define <- viewport(width=unit(2, "in"), height=unit(2, "in"))
  affine <- affineGrob(grob, vp_define=vp_define)
  grid.newpage()
  pushViewport(viewport(width=unit(4, "in"), height=unit(2, "in")))
  grid.draw(affine)
  popViewport()
}
if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  settings <- affine_settings(xy = list(x = c(3/3, 2/3, 0/3, 1/3),
                                        y = c(2/3, 1/3, 1/3, 2/3)),
                              unit = "snpc")
  affine <- affineGrob(grob,
                       vp_define = vp_define,
                       transform = settings$transform,
                       vp_use = settings$vp)
  grid.newpage()
  grid.draw(affine)
}

Description

affiner_options() returns the affiner package's global options.

Usage

affiner_options(..., default = FALSE)

Arguments

Value

A list of option values. Note this function does not set option values itself but this list can be passed to options(), withr::local_options(), or withr::with_options().

See Also

affiner for a high-level description of relevant global options.

Examples

affiner_options()

  affiner_options(default = TRUE)

  affiner_options(affiner_angular_unit = "pi-radians")

Description

angle() creates angle vectors with user specified angular unit. around as_angle() for those angular units.

Usage

angle(x = numeric(), unit = getOption("affiner_angular_unit", "degrees"))

degrees(x)

gradians(x)

pi_radians(x)

radians(x)

turns(x)

Arguments

Value

A numeric vector of class "angle". Its "unit" attribute is a standardized string of the specified angular unit.

See Also

as_angle(), angular_unit(), and angle-methods. https://en.wikipedia.org/wiki/Angle#Units for more information about angular units.

Examples

# Different representations of the "same" angle
  angle(180, "degrees")
  angle(pi, "radians")
  angle(0.5, "turns")
  angle(200, "gradians")
  pi_radians(1)

  a1 <- angle(180, "degrees")
  angular_unit(a1)
  is_angle(a1)
  as.numeric(a1, "radians")
  cos(a1)

  a2 <- as_angle(a1, "radians")
  angular_unit(a2)
  is_congruent(a1, a2)

Description

We implemented methods for several base generics for the angle() vectors.

Usage

## S3 method for class 'angle'
as.double(x, unit = angular_unit(x), ...)

## S3 method for class 'angle'
as.complex(x, modulus = 1, ...)

## S3 method for class 'angle'
format(x, unit = angular_unit(x), ..., use_unicode = is_utf8_output())

## S3 method for class 'angle'
print(x, unit = angular_unit(x), ..., use_unicode = is_utf8_output())

## S3 method for class 'angle'
abs(x)

Arguments

Details

• Mathematical Ops (in particular + and -) for two angle vectors will (if necessary) set the second vector's angular_unit() to match the first.

• as.numeric() takes a unit argument which can be used to convert angles into other angular units e.g. angle(x, "degrees") |> as.numeric("radians") to cast a numeric vector x from degrees to radians.

• abs() will calculate the angle modulo full turns.

• Use is_congruent() to test if two angles are congruent instead of == or all.equal().

• Not all implemented methods are documented here and since angle() is a numeric() class many other S3 generics besides the explicitly implemented ones should also work with it.

Value

Typical values as usually returned by these base generics.

Examples

# Two "congruent" angles
  a1 <- angle(180, "degrees")
  a2 <- angle(pi, "radians")

  print(a1)
  print(a1, unit = "radians")
  print(a1, unit = "pi-radians")

  cos(a1)
  sin(a1)
  tan(a1)

  # mathematical operations will coerce second `angle()` object to
  # same `angular_unit()` as the first one
  a1 + a2
  a1 - a2

  as.numeric(a1)
  as.numeric(a1, "radians")
  as.numeric(a1, "turns")

  # Use `is_congruent()` to check if two angles are "congruent"
  a1 == a2
  isTRUE(all.equal(a1, a2))
  is_congruent(a1, a2)
  is_congruent(a1, a2, mod_turns = FALSE)
  a3 <- angle(-180, "degrees") # Only congruent modulus full turns
  a1 == a3
  isTRUE(all.equal(a1, a2))
  is_congruent(a1, a3)
  is_congruent(a1, a3, mod_turns = FALSE)

Description

angular_unit() gets/sets the angular unit of angle() vectors.

Usage

angular_unit(x)

angular_unit(x) <- value

Arguments

Value

angular_unit() returns a string of x's angular unit.

Examples

a <- angle(seq(0, 360, by = 90), "degrees")
angular_unit(a)
print(a)
angular_unit(a) <- "turns"
angular_unit(a)
print(a)

Description

as_angle() casts to an angle() vector

Usage

as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'angle'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'character'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'complex'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'Coord2D'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'Coord3D'
as_angle(
  x,
  unit = getOption("affiner_angular_unit", "degrees"),
  type = c("azimuth", "inclination"),
  ...
)

## S3 method for class 'Line2D'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

## S3 method for class 'Plane3D'
as_angle(
  x,
  unit = getOption("affiner_angular_unit", "degrees"),
  type = c("azimuth", "inclination"),
  ...
)

## S3 method for class 'numeric'
as_angle(x, unit = getOption("affiner_angular_unit", "degrees"), ...)

Arguments

Value

An angle() vector

Examples

as_angle(angle(pi, "radians"), "pi-radians")
as_angle(complex(real = 0, imaginary = 1), "degrees")
as_angle(as_coord2d(x = 0, y = 1), "turns")
as_angle(200, "gradians")

Description

as_coord1d() casts to a Coord1D class object

Usage

as_coord1d(x, ...)

## S3 method for class 'character'
as_coord1d(x, ...)

## S3 method for class 'Coord2D'
as_coord1d(
  x,
  permutation = c("xy", "yx"),
  ...,
  line = as_line2d("x-axis"),
  scale = 0
)

## S3 method for class 'data.frame'
as_coord1d(x, ...)

## S3 method for class 'list'
as_coord1d(x, ...)

## S3 method for class 'matrix'
as_coord1d(x, ...)

## S3 method for class 'numeric'
as_coord1d(x, ...)

## S3 method for class 'Coord1D'
as_coord1d(x, ...)

## S3 method for class 'Point1D'
as_coord1d(x, ...)

Arguments

Value

A Coord1D class object

Examples

as_coord1d(x = rnorm(10))

Description

as_coord2d() casts to a Coord2D class object

Usage

as_coord2d(x, ...)

## S3 method for class 'angle'
as_coord2d(x, radius = 1, ...)

## S3 method for class 'character'
as_coord2d(x, ...)

## S3 method for class 'complex'
as_coord2d(x, ...)

## S3 method for class 'Coord3D'
as_coord2d(
  x,
  permutation = c("xyz", "xzy", "yxz", "yzx", "zyx", "zxy"),
  ...,
  plane = as_plane3d("xy-plane"),
  scale = 0,
  alpha = angle(45, "degrees")
)

## S3 method for class 'data.frame'
as_coord2d(x, ...)

## S3 method for class 'list'
as_coord2d(x, ...)

## S3 method for class 'matrix'
as_coord2d(x, ...)

## S3 method for class 'numeric'
as_coord2d(x, y = rep_len(0, length(x)), ...)

## S3 method for class 'Coord2D'
as_coord2d(x, ...)

Arguments

Value

A Coord2D class object

Examples

df <- data.frame(x = sample.int(10, 3),
                 y = sample.int(10, 3))
as_coord2d(df)
as_coord2d(complex(real = 3, imaginary = 2))
as_coord2d(angle(90, "degrees"), radius = 2)
as_coord2d(as_coord3d(1, 2, 2), alpha = degrees(90), scale = 0.5)

Description

as_coord3d() casts to a Coord3D class object

Usage

as_coord3d(x, ...)

## S3 method for class 'angle'
as_coord3d(x, radius = 1, inclination = NULL, z = NULL, ...)

## S3 method for class 'character'
as_coord3d(x, ...)

## S3 method for class 'data.frame'
as_coord3d(x, ..., z = NULL)

## S3 method for class 'list'
as_coord3d(x, ..., z = NULL)

## S3 method for class 'matrix'
as_coord3d(x, ...)

## S3 method for class 'numeric'
as_coord3d(x, y = rep_len(0, length(x)), z = rep_len(0, length(x)), ...)

## S3 method for class 'Coord3D'
as_coord3d(x, ...)

## S3 method for class 'Coord2D'
as_coord3d(x, z = rep_len(0, length(x)), ...)

Arguments

Value

A Coord3D class object

Examples

as_coord3d(x = 1, y = 2, z = 3)
df <- data.frame(x = sample.int(10, 3),
                 y = sample.int(10, 3),
                 z = sample.int(10, 3))
as_coord3d(df)
# Cylindrical coordinates
as_coord3d(degrees(90), z = 1, radius = 1)
# Spherical coordinates
as_coord3d(degrees(90), inclination = degrees(90), radius = 1)

Description

as_line2d() casts to a Line2D object.

Usage

as_line2d(...)

## S3 method for class 'numeric'
as_line2d(a, b, c, ...)

## S3 method for class 'angle'
as_line2d(theta, p1 = as_coord2d("origin"), ...)

## S3 method for class 'character'
as_line2d(x, ...)

## S3 method for class 'Coord2D'
as_line2d(normal, p1 = as_coord3d("origin"), p2, ...)

## S3 method for class 'Line2D'
as_line2d(line, ...)

## S3 method for class 'Point1D'
as_line2d(point, b = 0, ...)

Arguments

Examples

p1 <- as_coord2d(x = 5, y = 10)
p2 <- as_coord2d(x = 7, y = 12)
theta <- degrees(45)
as_line2d(theta, p1)
as_line2d(p1, p2)

Description

as_plane3d() casts to a Plane3D object.

Usage

as_plane3d(...)

## S3 method for class 'numeric'
as_plane3d(a, b, c, d, ...)

## S3 method for class 'character'
as_plane3d(x, ...)

## S3 method for class 'Coord3D'
as_plane3d(normal, p1 = as_coord3d("origin"), p2, p3, ...)

## S3 method for class 'Plane3D'
as_plane3d(plane, ...)

## S3 method for class 'Point1D'
as_plane3d(point, b = 0, c = 0, ...)

## S3 method for class 'Line2D'
as_plane3d(line, c = 0, ...)

Arguments

Description

as_point1d() casts to a Point1D object.

Usage

as_point1d(...)

## S3 method for class 'numeric'
as_point1d(a, b, ...)

## S3 method for class 'character'
as_point1d(x, ...)

## S3 method for class 'Coord1D'
as_point1d(normal, ...)

## S3 method for class 'Point1D'
as_point1d(point, ...)

Arguments

Examples

p1 <- as_point1d(a = 1, b = 0)

Description

as_transform1d() casts to a transform1d() affine transformation matrix

Usage

as_transform1d(x, ...)

## S3 method for class 'transform1d'
as_transform1d(x, ...)

## Default S3 method:
as_transform1d(x, ...)

Arguments

Value

A transform1d() object

Examples

m <- diag(2L)
as_transform1d(m)

Description

as_transform2d() casts to a transform2d() affine transformation matrix

Usage

as_transform2d(x, ...)

## S3 method for class 'transform2d'
as_transform2d(x, ...)

## Default S3 method:
as_transform2d(x, ...)

Arguments

Value

A transform2d() object

Examples

m <- diag(3L)
as_transform2d(m)

Description

as_transform3d() casts to a transform3d() affine transformation matrix

Usage

as_transform3d(x, ...)

## S3 method for class 'transform3d'
as_transform3d(x, ...)

## Default S3 method:
as_transform3d(x, ...)

Arguments

Value

A transform3d() object

Examples

m <- diag(4L)
as_transform3d(m)

Description

range() computes axis-aligned ranges for Coord1D, Coord2D, and Coord3D class objects.

Usage

## S3 method for class 'Coord1D'
range(..., na.rm = FALSE)

## S3 method for class 'Coord2D'
range(..., na.rm = FALSE)

## S3 method for class 'Coord3D'
range(..., na.rm = FALSE)

Arguments

Value

Either a Coord1D, Coord2D, or Coord3D object of length two. The first element will have the minimum x/y(/z) coordinates and the second element will have the maximum x/y(/z) coordinates of the axis-aligned ranges.

Examples

range(as_coord2d(rnorm(5), rnorm(5)))
range(as_coord3d(rnorm(5), rnorm(5), rnorm(5)))

Description

mean()computes centroids for Coord1D, Coord2D, and Coord3D class objects

Usage

## S3 method for class 'Coord1D'
mean(x, ...)

## S3 method for class 'Coord2D'
mean(x, ...)

## S3 method for class 'Coord3D'
mean(x, ...)

Arguments

Value

A Coord1D, Coord2D, or Coord3D class object of length one

Examples

p <- as_coord2d(x = 1:4, y = 1:4)
print(mean(p))
print(sum(p) / length(p)) # less efficient alternative

p <- as_coord3d(x = 1:4, y = 1:4, z = 1:4)
print(mean(p))

Description

convex_hull2d() is a S3 generic for computing the convex hull of an object. There is an implemented method supporting Coord2D class objects using grDevices::chull() to compute the convex hull.

Usage

convex_hull2d(x, ...)

## S3 method for class 'Coord2D'
convex_hull2d(x, ...)

Arguments

Value

An object of same class as x representing just the subset of points on the convex hull. The method for Coord2D class objects returns these points in counter-clockwise order.

Examples

p <- as_coord2d(x = rnorm(25), y = rnorm(25))
print(convex_hull2d(p))

# Equivalent to following caculation using `grDevices::chull()`
all.equal(convex_hull2d(p),
          p[rev(grDevices::chull(as.list(p)))])

Description

Coord1D is an R6::R6Class() object representing two-dimensional points represented by Cartesian Coordinates.

Active bindings

Methods

Public methods

• Coord1D$new()

• Coord1D$print()

• Coord1D$project()

• Coord1D$reflect()

• Coord1D$scale()

• Coord1D$translate()

• Coord1D$transform()

• Coord1D$clone()

Method new()

Usage

Coord1D$new(xw)

Arguments

Method print()

Usage

Coord1D$print(n = NULL, ...)

Arguments

Method project()

Usage

Coord1D$project(point = as_point1d("origin"), ...)

Arguments

Method reflect()

Usage

Coord1D$reflect(point = as_point1d("origin"), ...)

Arguments

Method scale()

Usage

Coord1D$scale(x_scale = 1)

Arguments

Method translate()

Usage

Coord1D$translate(x = as_coord1d(0), ...)

Arguments

Method transform()

Usage

Coord1D$transform(mat = transform1d())

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Coord1D$clone(deep = FALSE)

Arguments

Examples

p <- as_coord1d(x = rnorm(100, 2))
print(p, n = 10L)
pc <- mean(p) # Centroid
# method chained affine transformation matrices are auto-pre-multiplied
p$
  translate(-pc)$
  reflect("origin")$
  print(n = 10L)

Description

Coord2D is an R6::R6Class() object representing two-dimensional points represented by Cartesian Coordinates.

Active bindings

Methods

Public methods

• Coord2D$new()

• Coord2D$permute()

• Coord2D$print()

• Coord2D$project()

• Coord2D$reflect()

• Coord2D$rotate()

• Coord2D$scale()

• Coord2D$shear()

• Coord2D$translate()

• Coord2D$transform()

• Coord2D$clone()

Method new()

Usage

Coord2D$new(xyw)

Arguments

Method permute()

Usage

Coord2D$permute(permutation = c("xy", "yx"))

Arguments

Method print()

Usage

Coord2D$print(n = NULL, ...)

Arguments

Method project()

Usage

Coord2D$project(line = as_line2d("x-axis"), ..., scale = 0)

Arguments

Method reflect()

Usage

Coord2D$reflect(line = as_line2d("x-axis"), ...)

Arguments

Method rotate()

Usage

Coord2D$rotate(theta = angle(0), ...)

Arguments

Method scale()

Usage

Coord2D$scale(x_scale = 1, y_scale = x_scale)

Arguments

Method shear()

Usage

Coord2D$shear(xy_shear = 0, yx_shear = 0)

Arguments

Method translate()

Usage

Coord2D$translate(x = as_coord2d(0, 0), ...)

Arguments

Method transform()

Usage

Coord2D$transform(mat = transform2d())

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Coord2D$clone(deep = FALSE)

Arguments

Examples

p <- as_coord2d(x = rnorm(100, 2), y = rnorm(100, 2))
print(p, n = 10)
pc <- mean(p) # Centroid
# method chained affine transformation matrices are auto-pre-multiplied
p$
  translate(-pc)$
  shear(x = 1, y = 0)$
  reflect("x-axis")$
  rotate(90, "degrees")$
  print(n = 10)

Description

Coord3D is an R6::R6Class() object representing three-dimensional points represented by Cartesian Coordinates.

Active bindings

Methods

Public methods

• Coord3D$new()

• Coord3D$permute()

• Coord3D$print()

• Coord3D$project()

• Coord3D$reflect()

• Coord3D$rotate()

• Coord3D$scale()

• Coord3D$shear()

• Coord3D$translate()

• Coord3D$transform()

• Coord3D$clone()

Method new()

Usage

Coord3D$new(xyzw)

Arguments

Method permute()

Usage

Coord3D$permute(permutation = c("xyz", "xzy", "yxz", "yzx", "zyx", "zxy"))

Arguments

Method print()

Usage

Coord3D$print(n = NULL, ...)

Arguments

Method project()

Usage

Coord3D$project(
  plane = as_plane3d("xy-plane"),
  ...,
  scale = 0,
  alpha = angle(45, "degrees")
)

Arguments

Method reflect()

Usage

Coord3D$reflect(plane = as_plane3d("xy-plane"), ...)

Arguments

Method rotate()

Usage

Coord3D$rotate(axis = as_coord3d("z-axis"), theta = angle(0), ...)

Arguments

Method scale()

Usage

Coord3D$scale(x_scale = 1, y_scale = x_scale, z_scale = x_scale)

Arguments

Method shear()

Usage

Coord3D$shear(
  xy_shear = 0,
  xz_shear = 0,
  yx_shear = 0,
  yz_shear = 0,
  zx_shear = 0,
  zy_shear = 0
)

Arguments

Method translate()

Usage

Coord3D$translate(x = as_coord3d(0, 0, 0), ...)

Arguments

Method transform()

Usage

Coord3D$transform(mat = transform3d())

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Coord3D$clone(deep = FALSE)

Arguments

Examples

p <- as_coord3d(x = rnorm(100, 2), y = rnorm(100, 2), z = rnorm(100, 2))
print(p, n = 10)
pc <- mean(p) # Centroid
# method chained affine transformation matrices are auto-pre-multiplied
p$
  translate(-pc)$
  reflect("xy-plane")$
  rotate("z-axis", degrees(90))$
  print(n = 10)

Description

cross_product3d() computes the cross product of two Coord3D class vectors.

Usage

cross_product3d(x, y)

Arguments

Value

A Coord3D class vector

Examples

x <- as_coord3d(2, 3, 4)
y <- as_coord3d(5, 6, 7)
cross_product3d(x, y)

Description

distance1d() computes 1D Euclidean distances.

Usage

distance1d(x, y)

Arguments

Examples

p <- as_coord1d(x = 1:4)
distance1d(p, as_coord1d(0))

Description

distance2d() computes 2D Euclidean distances.

Usage

distance2d(x, y)

Arguments

Examples

p <- as_coord2d(x = 1:4, y = 1:4)
distance2d(p, as_coord2d(0, 0))

Description

distance3d() computes 3D Euclidean distances.

Usage

distance3d(x, y)

Arguments

Examples

p <- as_coord3d(x = 1:4, y = 1:4, z = 1:4)
distance3d(p, as_coord3d("origin"))

Description

plot() plots Coord1D and Coord2D class objects while points() draws Coord1D and Coord2D class objects and lines() draws Point1D and Line2D class objects to an existing plot. If the suggested ggplot2 and rgl packages are available we also register ggplot2::autolayer() methods for Coord1D, Coord2D, Point1D, and Line2D class objects and a rgl::plot3d() method for Coord3D class objects.

Usage

## S3 method for class 'Coord1D'
plot(x, ...)

## S3 method for class 'Coord1D'
points(x, ...)

## S3 method for class 'Point1D'
lines(x, ...)

## S3 method for class 'Coord2D'
plot(x, ...)

## S3 method for class 'Coord2D'
points(x, ...)

## S3 method for class 'Line2D'
lines(x, ...)

Arguments

Value

Used for its side effect of drawing to the graphics device.

Examples

c1 <- as_coord2d(x = 0, y = 1:10)
l <- as_line2d(a = 1, b = -1, c = 0) # y = x
c2 <- c1$clone()$reflect(l)
plot(c1, xlim = c(-1, 11), ylim = c(-1, 11),
     main = "2D reflection across a line")
lines(l)
points(c2, col = "red")

c1 <- as_coord2d(x = 1:10, y = 1:10)
l <- as_line2d(a = -1, b = 0, c = 0) # x = 0
c2 <- c1$clone()$project(l)
if (require("ggplot2", quietly = TRUE,
            include.only = c("ggplot", "autolayer", "labs"))) {
  ggplot() +
      autolayer(c1) +
      autolayer(l) +
      autolayer(c2, color = "red") +
      labs(title = "2D projection onto a line")
}

c1 <- as_coord1d(x = seq.int(-4, -1))
pt <- as_point1d(a = 1, b = 0) # x = 0
c2 <- c1$clone()$reflect(pt)
plot(c1, xlim = c(-5, 5), main = "1D reflection across a point")
lines(pt)
points(c2, col = "red")

# 3D reflection across a plane
c1 <- as_coord3d(x = 1:10, y = 1:10, z = 1:10)
pl <- as_plane3d(a = 0, b = 0, c = -1, d = 2) # z = 2
c2 <- c1$clone()$reflect(pl)
if (require("rgl", quietly = TRUE, 
            include.only = c("plot3d", "planes3d", "points3d"))) {
  plot3d(c1, size = 8)
  planes3d(as.data.frame(pl), d =  pl$d, color = "grey", alpha = 0.6)
  points3d(as.data.frame(c2), col = "red", size = 8)
}

Description

arcsine(), arccosine(), arctangent(), arcsecant(), arccosecant(), and arccotangent() are inverse trigonometric functions that return angle() vectors with a user chosen angular unit.

Usage

arcsine(
  x,
  unit = getOption("affiner_angular_unit", "degrees"),
  tolerance = sqrt(.Machine$double.eps)
)

arccosine(
  x,
  unit = getOption("affiner_angular_unit", "degrees"),
  tolerance = sqrt(.Machine$double.eps)
)

arctangent(x, unit = getOption("affiner_angular_unit", "degrees"), y = NULL)

arcsecant(x, unit = getOption("affiner_angular_unit", "degrees"))

arccosecant(x, unit = getOption("affiner_angular_unit", "degrees"))

arccotangent(x, unit = getOption("affiner_angular_unit", "degrees"))

Arguments

Value

An angle() vector

Examples

arccosine(-1, "degrees")
arcsine(0, "turns")
arctangent(0, "gradians")
arccosecant(-1, "degrees")
arcsecant(1, "degrees")
arccotangent(1, "half-turns")

# `base::atan2(y, x)` computes the angle of the vector from origin to (x, y)
as_angle(as_coord2d(x = 1, y = 1), "degrees")

Description

is_angle() tests whether an object is an angle vector

Usage

is_angle(x)

Arguments

Value

A logical value

Examples

a <- angle(180, "degrees")
is_angle(a)
is_angle(pi)

Description

is_congruent() is a S3 generic that tests whether two different objects are “congruent”. The is_congruent() method for angle() classes tests whether two angles are congruent.

Usage

is_congruent(x, y, ...)

## S3 method for class 'numeric'
is_congruent(x, y, ..., tolerance = sqrt(.Machine$double.eps))

## S3 method for class 'angle'
is_congruent(
  x,
  y,
  ...,
  mod_turns = TRUE,
  tolerance = sqrt(.Machine$double.eps)
)

Arguments

Value

A logical vector

Examples

# Use `is_congruent()` to check if two angles are "congruent"
  a1 <- angle(180, "degrees")
  a2 <- angle(pi, "radians")
  a3 <- angle(-180, "degrees") # Only congruent modulus full turns
  a1 == a2
  isTRUE(all.equal(a1, a2))
  is_congruent(a1, a2)
  is_congruent(a1, a2, mod_turns = FALSE)
  a1 == a3
  isTRUE(all.equal(a1, a3))
  is_congruent(a1, a3)
  is_congruent(a1, a3, mod_turns = FALSE)

Description

is_coord1d() tests whether an object has a "Coord1D" class

Usage

is_coord1d(x)

Arguments

Value

A logical value

Examples

p <- as_coord1d(x = sample.int(10, 3))
is_coord1d(p)

Description

is_coord2d() tests whether an object has a "Coord2D" class

Usage

is_coord2d(x)

Arguments

Value

A logical value

Examples

p <- as_coord2d(x = sample.int(10, 3), y = sample.int(10, 3))
is_coord2d(p)

Description

is_coord3d() tests whether an object has a "Coord3D" class

Usage

is_coord3d(x)

Arguments

Value

A logical value

Examples

p <- as_coord3d(x = sample.int(10, 3),
                y = sample.int(10, 3),
                z = sample.int(10, 3))
is_coord3d(p)

Description

is_line2d() tests whether an object has a "Line2D" class

Usage

is_line2d(x)

Arguments

Value

A logical value

Examples

l <- as_line2d(a = 1, b = 2, c = 3)
is_line2d(l)

Description

is_plane3d() tests whether an object has a "Plane3D" class

Usage

is_plane3d(x)

Arguments

Value

A logical value

Examples

p <- as_plane3d(a = 1, b = 2, c = 3, 4)
is_plane3d(p)

Description

is_point1d() tests whether an object has a "Point1D" class

Usage

is_point1d(x)

Arguments

Value

A logical value

Examples

p <- as_point1d(a = 1, b = 5)
is_point1d(p)

Description

is_transform1d() tests if object is a transform1d() affine transformation matrix

Usage

is_transform1d(x)

Arguments

Value

A logical value

Examples

m <- transform1d(diag(2L))
is_transform1d(m)
is_transform1d(diag(2L))

Description

is_transform2d() tests if object is a transform2d() affine transformation matrix

Usage

is_transform2d(x)

Arguments

Value

A logical value

Examples

m <- transform2d(diag(3L))
is_transform2d(m)
is_transform2d(diag(3L))

Description

is_transform3d() tests if object is a transform3d() affine transformation matrix

Usage

is_transform3d(x)

Arguments

Value

A logical value

Examples

m <- transform3d(diag(4L))
is_transform3d(m)
is_transform3d(diag(4L))

Description

isometricCube() is a grid grob function to render isometric cube faces by automatically wrapping around affineGrob().

Usage

isocubeGrob(
  top,
  right,
  left,
  gp_border = grid::gpar(fill = NA, col = "black", lwd = 12),
  name = NULL,
  gp = grid::gpar(),
  vp = NULL
)

grid.isocube(...)

Arguments

Details

Any ggplot2 objects are coerced to grobs by ggplot2::ggplotGrob(). Depending on what you'd like to do you may want to instead manually convert a ggplot2 object gg to a grob with gtable::gtable_filter(ggplot2::ggplotGrob(gg), "panel").

Value

A grid::gTree() (grob) object of class "isocube". As a side effect grid.isocube() draws to the active graphics device.

Examples

if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
  # Only works if active graphics device supports affine transformations
  # such as `png(type="cairo")` on R 4.2+
  grid.newpage()
  gp_text <- gpar(fontsize = 72)
  grid.isocube(top = textGrob("top", gp = gp_text), 
               right = textGrob("right", gp = gp_text),
               left = textGrob("left", gp = gp_text))
}
if (require("grid") &&
    getRversion() >= "4.2.0" &&
    isTRUE(dev.capabilities()$transformations)) {
    colors <- c("#D55E00", "#009E73", "#56B4E9")
    spacings <- c(0.25, 0.2, 0.25)
    texts <- c("pkgname", "left\nface", "right\nface")
    rots <- c(45, 0, 0)
    fontsizes <- c(52, 80, 80)
    sides <- c("top", "left", "right")
    types <- gridpattern::names_polygon_tiling[c(5, 7, 9)]
    l_grobs <- list()
    grid.newpage()
    for (i in 1:3) {
        if (requireNamespace("gridpattern", quietly = TRUE)) {
            bg <- gridpattern::grid.pattern_polygon_tiling(
                       colour = "grey80",
                       fill = c(colors[i], "white"),
                       type = types[i],
                       spacing = spacings[i],
                       draw = FALSE)
        } else {
            bg <- rectGrob(gp = gpar(col = NA, fill = colors[i]))
        }
        text <- textGrob(texts[i], rot = rots[i],
                         gp = gpar(fontsize = fontsizes[i]))
        l_grobs[[sides[i]]] <- grobTree(bg, text)
    }
  grid.newpage()
  grid.isocube(top = l_grobs$top, 
               right = l_grobs$right,
               left = l_grobs$left)
}

Description

Line2D is an R6::R6Class() object representing two-dimensional lines.

Public fields

Methods

Public methods

• Line2D$new()

• Line2D$print()

• Line2D$clone()

Method new()

Usage

Line2D$new(a, b, c)

Arguments

Method print()

Usage

Line2D$print(n = NULL, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Line2D$clone(deep = FALSE)

Arguments

Examples

p1 <- as_coord2d(x = 5, y = 10)
p2 <- as_coord2d(x = 7, y = 12)
theta <- degrees(45)
as_line2d(theta, p1)
as_line2d(p1, p2)

Description

normal2d() is an S3 generic that computes a 2D normal vector.

Usage

normal2d(x, ...)

## S3 method for class 'Coord2D'
normal2d(x, ..., normalize = TRUE)

## S3 method for class 'Line2D'
normal2d(x, ..., normalize = TRUE)

Arguments

Value

A Coord2D (normal) vector

Examples

p <- as_coord2d(x = 2, y = 3)
  normal2d(p)
  normal2d(p, normalize = FALSE)

Description

normal3d() is an S3 generic that computes a 3D normal vector.

Usage

normal3d(x, ...)

## S3 method for class 'Coord3D'
normal3d(x, cross, ..., normalize = TRUE)

## S3 method for class 'character'
normal3d(x, ..., normalize = TRUE)

## S3 method for class 'Plane3D'
normal3d(x, ..., normalize = TRUE)

Arguments

Value

A Coord3D (normal) vector

Examples

normal3d("xy-plane")
normal3d(as_coord3d(2, 0, 0), cross = as_coord3d(0, 2, 0))

Description

Plane3D is an R6::R6Class() object representing three-dimensional planes.

Public fields

Methods

Public methods

• Plane3D$new()

• Plane3D$print()

• Plane3D$clone()

Method new()

Usage

Plane3D$new(a, b, c, d)

Arguments

Method print()

Usage

Plane3D$print(n = NULL, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Plane3D$clone(deep = FALSE)

Arguments

Description

Point1D is an R6::R6Class() object representing one-dimensional points.

Public fields

Methods

Public methods

• Point1D$new()

• Point1D$print()

• Point1D$clone()

Method new()

Usage

Point1D$new(a, b)

Arguments

Method print()

Usage

Point1D$print(n = NULL, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Point1D$clone(deep = FALSE)

Arguments

Examples

p1 <- as_point1d(a = 1, b = 5)

Description

rotate3d_to_AA() converts from (post-multiplied) rotation matrix to an axis-angle representation of 3D rotations.

Usage

rotate3d_to_AA(
  mat = diag(4),
  unit = getOption("affiner_angular_unit", "degrees")
)

Arguments

See Also

https://en.wikipedia.org/wiki/Axis-angle_representation for more details about the Axis-angle representation of 3D rotations. rotate3d() can be used to convert from an axis-angle representation to a rotation matrix.

Examples

# axis-angle representation of 90 degree rotation about the x-axis
 rotate3d_to_AA(rotate3d("x-axis", 90, unit = "degrees"))

 # find Axis-Angle representation of first rotating about x-axis 180 degrees
 # and then rotating about z-axis 45 degrees
 R <- rotate3d("x-axis", 180, unit = "degrees") %*%
        rotate3d("z-axis", 45, unit = "degrees")
 AA <- rotate3d_to_AA(R)

 # Can use `rotate3d()` to convert back to rotation matrix representation
 all.equal(R, do.call(rotate3d, AA))

Description

transform1d(), reflect1d(), scale2d(), and translate1d() create 1D affine transformation matrix objects.

Usage

transform1d(mat = diag(2L))

project1d(point = as_point1d("origin"), ...)

reflect1d(point = as_point1d("origin"), ...)

scale1d(x_scale = 1)

translate1d(x = as_coord1d(0), ...)

Arguments

Details

transform1d()

User supplied (post-multiplied) affine transformation matrix

.

reflect1d()

Reflections across a point.

scale1d()

Scale the x-coordinates by multiplicative scale factors.

translate1d()

Translate the coordinates by a Coord1D class object parameter.

transform1d() 1D affine transformation matrix objects are meant to be post-multiplied and therefore should not be multiplied in reverse order. Note the Coord1D class object methods auto-pre-multiply affine transformations when "method chaining" so pre-multiplying affine transformation matrices to do a single cumulative transformation instead of a method chain of multiple transformations will not improve performance as much as as it does in other R packages.

To convert a pre-multiplied 1D affine transformation matrix to a post-multiplied one simply compute its transpose using t(). To get an inverse transformation matrix from an existing transformation matrix that does the opposite transformations simply compute its inverse using solve().

Value

A 2x2 post-multiplied affine transformation matrix with classes "transform1d" and "at_matrix"

Examples

p <- as_coord1d(x = sample(1:10, 3))

# {affiner} affine transformation matrices are post-multiplied
# and therefore should **not** go in reverse order
mat <- transform1d(diag(2)) %*%
         scale1d(2) %*%
         translate1d(x = -1)
p1 <- p$
  clone()$
  transform(mat)

# The equivalent result appyling affine transformations via method chaining
p2 <- p$
  clone()$
  transform(diag(2))$
  scale(2)$
  translate(x = -1)

all.equal(p1, p2)

Description

transform2d(), project2d(), reflect2d(), rotate2d(), scale2d(), shear2d(), and translate2d() create 2D affine transformation matrix objects.

Usage

transform2d(mat = diag(3L))

permute2d(permutation = c("xy", "yx"))

project2d(line = as_line2d("x-axis"), ..., scale = 0)

reflect2d(line = as_line2d("x-axis"), ...)

rotate2d(theta = angle(0), ...)

scale2d(x_scale = 1, y_scale = x_scale)

shear2d(xy_shear = 0, yx_shear = 0)

translate2d(x = as_coord2d(0, 0), ...)

Arguments

Details

transform2d()

User supplied (post-multiplied) affine transformation matrix

.

project2d()

Oblique vector projections onto a line parameterized by an oblique projection scale factor. A (degenerate) scale factor of zero results in an orthogonal projection.

reflect2d()

Reflections across a line. To "flip" across both the x-axis and the y-axis use scale2d(-1).

rotate2d()

Rotations around the origin parameterized by an angle().

scale2d()

Scale the x-coordinates and/or the y-coordinates by multiplicative scale factors.

shear2d()

Shear the x-coordinates and/or the y-coordinates using shear factors.

translate2d()

Translate the coordinates by a Coord2D class object parameter.

transform2d() 2D affine transformation matrix objects are meant to be post-multiplied and therefore should not be multiplied in reverse order. Note the Coord2D class object methods auto-pre-multiply affine transformations when "method chaining" so pre-multiplying affine transformation matrices to do a single cumulative transformation instead of a method chain of multiple transformations will not improve performance as much as as it does in other R packages.

To convert a pre-multiplied 2D affine transformation matrix to a post-multiplied one simply compute its transpose using t(). To get an inverse transformation matrix from an existing transformation matrix that does the opposite transformations simply compute its inverse using solve().

Value

A 3x3 post-multiplied affine transformation matrix with classes "transform2d" and "at_matrix"

Examples

p <- as_coord2d(x = sample(1:10, 3), y = sample(1:10, 3))

# {affiner} affine transformation matrices are post-multiplied
# and therefore should **not** go in reverse order
mat <- transform2d(diag(3)) %*%
         reflect2d(as_coord2d(-1, 1)) %*%
         rotate2d(90, "degrees") %*%
         scale2d(1, 2) %*%
         shear2d(0.5, 0.5) %*%
         translate2d(x = -1, y = -1)
p1 <- p$
  clone()$
  transform(mat)

# The equivalent result appyling affine transformations via method chaining
p2 <- p$
  clone()$
  transform(diag(3L))$
  reflect(as_coord2d(-1, 1))$
  rotate(90, "degrees")$
  scale(1, 2)$
  shear(0.5, 0.5)$
  translate(x = -1, y = -1)

all.equal(p1, p2)

Description

transform3d(), project3d(), reflect3d(), rotate3d(), scale3d(), shear3d(), and translate3d() create 3D affine transformation matrix objects.

Usage

transform3d(mat = diag(4L))

permute3d(permutation = c("xyz", "xzy", "yxz", "yzx", "zyx", "zxy"))

project3d(
  plane = as_plane3d("xy-plane"),
  ...,
  scale = 0,
  alpha = angle(45, "degrees")
)

reflect3d(plane = as_plane3d("xy-plane"), ...)

rotate3d(axis = as_coord3d("z-axis"), theta = angle(0), ...)

scale3d(x_scale = 1, y_scale = x_scale, z_scale = x_scale)

shear3d(
  xy_shear = 0,
  xz_shear = 0,
  yx_shear = 0,
  yz_shear = 0,
  zx_shear = 0,
  zy_shear = 0
)

translate3d(x = as_coord3d(0, 0, 0), ...)

Arguments

Details

transform3d()

User supplied (post-multiplied) affine transformation matrix

.

scale3d()

Scale the x-coordinates and/or the y-coordinates and/or the z-coordinates by multiplicative scale factors.

shear3d()

Shear the x-coordinates and/or the y-coordinates and/or the z-coordinates using shear factors.

translate3d()

Translate the coordinates by a Coord3D class object parameter.

transform3d() 3D affine transformation matrix objects are meant to be post-multiplied and therefore should not be multiplied in reverse order. Note the Coord3D class object methods auto-pre-multiply affine transformations when "method chaining" so pre-multiplying affine transformation matrices to do a single cumulative transformation instead of a method chain of multiple transformations will not improve performance as much as as it does in other R packages.

To convert a pre-multiplied 3D affine transformation matrix to a post-multiplied one simply compute its transpose using t(). To get an inverse transformation matrix from an existing transformation matrix that does the opposite transformations simply compute its inverse using solve().

Value

A 4x4 post-multiplied affine transformation matrix with classes "transform3d" and "at_matrix"

Examples

p <- as_coord3d(x = sample(1:10, 3), y = sample(1:10, 3), z = sample(1:10, 3))

# {affiner} affine transformation matrices are post-multiplied
# and therefore should **not** go in reverse order
mat <- transform3d(diag(4L)) %*%
         rotate3d("z-axis", degrees(90)) %*%
         scale3d(1, 2, 1) %*%
         translate3d(x = -1, y = -1, z = -1)
p1 <- p$
  clone()$
  transform(mat)

# The equivalent result appyling affine transformations via method chaining
p2 <- p$
  clone()$
  transform(diag(4L))$
  rotate("z-axis", degrees(90))$
  scale(1, 2, 1)$
  translate(x = -1, y = -1, z = -1)

all.equal(p1, p2)

Description

sine(), cosine(), tangent(), secant(), cosecant(), and cotangent() are angle() aware trigonometric functions that allow for a user chosen angular unit.

Usage

sine(x, unit = getOption("affiner_angular_unit", "degrees"))

cosine(x, unit = getOption("affiner_angular_unit", "degrees"))

tangent(x, unit = getOption("affiner_angular_unit", "degrees"))

secant(x, unit = getOption("affiner_angular_unit", "degrees"))

cosecant(x, unit = getOption("affiner_angular_unit", "degrees"))

cotangent(x, unit = getOption("affiner_angular_unit", "degrees"))

Arguments

Value

A numeric vector

Examples

sine(pi, "radians")
cosine(180, "degrees")
tangent(0.5, "turns")

a <- angle(0.5, "turns")
secant(a)
cosecant(a)
cotangent(a)