# geometry_utils: Helper functions for making geometric calculations. In trevorld/piecepack: Board Game Graphics

## Description

`to_x`, `to_y`, `to_r`, `to_t` convert between polar coordinates (in degrees) and Cartesian coordinates. `to_degrees` and `to_radians` converts between degrees and radians. `AA_to_R` and `R_to_AA` convert back and forth between (post-multiplied) rotation matrix and axis-angle representations of 3D rotations. `R_x`, `R_y`, and `R_z` build (post-multiplied) rotation matrices for simple rotations around the x, y, and z axes.

## Usage

 ``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21``` ```AA_to_R(angle = 0, axis_x = 0, axis_y = 0, axis_z = NA, ...) R_to_AA(R = diag(3)) R_x(angle = 0) R_y(angle = 0) R_z(angle = 0) to_radians(t) to_degrees(t) to_x(t, r) to_y(t, r) to_r(x, y) to_t(x, y) ```

## Arguments

 `angle` Angle in degrees (counter-clockwise) `axis_x` First coordinate of the axis unit vector. `axis_y` Second coordinate of the axis unit vector. `axis_z` Third coordinate of the axis unit vector (usually inferred). `...` Ignored `R` 3D rotation matrix (post-multiplied) `t` Angle in degrees (counter-clockwise) `r` Radial distance `x` Cartesian x coordinate `y` Cartesian y coordinate

## Details

`pp_cfg` uses polar coordinates to determine where the "primary" and "directional" symbols are located on a game piece. They are also useful for drawing certain shapes and for making game diagrams on hex boards.

`piecepackr` and `grid` functions use angles in degrees but the `base` trigonometry functions usually use radians.

`piecepackr`'s 3D graphics functions `save_piece_obj`, `piece`, and `piece3d` use the axis-angle representation for 3D rotations. The axis-angle representation involves specifying a unit vector indicating the direction of an axis of rotation and an angle describing the (counter-clockwise) rotation around that axis. Because it is a unit vector one only needs to specify the first two elements, `axis_x` and `axis_y`, and we are able to infer the 3rd element `axis_z`. The default of `axis = 0`, `axis_y = 0`, and implied `axis_z = 1` corresponds to a rotation around the z-axis which is reverse-compatible with the originally 2D `angle` interpretation in `grid.piece`. In order to figure out the appropriate axis-angle representation parameters `R_to_AA`, `R_x`, `R_y`, and `R_z` allow one to first come up with an appropriate (post-multiplied) 3D rotation matrix by chaining simple rotations and then convert them to the corresponding axis-angle representation. Pieces are rotated as if their center was at the origin.

https://en.wikipedia.org/wiki/Axis-angle_representation for more details about the Axis-angle representation of 3D rotations. See `Trig` for R's built-in trigonometric functions.
 ``` 1 2 3 4 5 6 7 8 9 10 11 12``` ``` to_x(90, 1) to_y(180, 0.5) to_t(0, -1) to_r(0.5, 0) all.equal(pi, to_radians(to_degrees(pi))) # default axis-angle axis is equivalent to a rotation about the z-axis all.equal(AA_to_R(angle=60), R_z(angle=60)) # axis-angle representation of 90 rotation about the x-axis R_to_AA(R_x(90)) # find Axis-Angle representation of first rotating about x-axis 180 degrees # and then rotating about z-axis 45 degrees R_to_AA(R_x(180) %*% R_z(45)) ```