Vectors Package Update

[ttchalakov]

This addition to the geometry package adds an abstract framework for geometric vectors which are distinctly different from linear algebra vectors as the polar, spherical, and cylindrical coordinate systems are not linear combinations of any basis. This design is chosen because the purpose of this pull request is to introduce tools for physical representations of locations in space through the addition of other common coordinate systems (polar, spherical, cylindrical). It is recommended to use EJML vectors to work with other vector quantities.

The packages includes templated interfaces to help generalize the designs of vectors for geometric applications. Currently cartesian 2D, polar, cartesian 3D, spherical, and cylindrical coordinate systems are implemented and unit tests. More can be added to this API but the current vectors are largely exhaustive for effectively all purposes. Bullet point 2 in Future Considerations includes ideas for other useful vectors.

Vectors for Geometry

A good vector library is clearly necessary. While EJML could be used directly for linear vector spaces such as cartesian, it doesn't work for polar, spherical, or cylindrical systems. On another note, a library for vectors that describe geometric locations can also provide many extra convenience features. It should be noted that this packages considers points to be distinct from vectors and that they do not have operations on them so making a point class would make a container object for the point. It is recommended to use vectors to represent locations in space from an origin.

The Coordinate Systems

Cartesian

The most familiar system to everyone is the cartesian system which is (x,y) and (x,y,z) in 2D and 3D respectively. If a review is needed follow this link.

Polar, Spherical, and Cylindrical

The polar coordinate systems is the ordered pair (r, theta) where theta is in radians. Polar coordinates along with spherical and cylindrical are implemented to be bijective from all other coordinate systems. A bijective coordinate system is injective and surjective meaning that there is a unique values from one coordinate system to another and that all values can be converted. However in the case of r and rho equal to 0 any theta can be used to describe values along the z axis in cylindrical coordinate and any theta value can be used for the spherical system to represent the origin at (0,0,0) cartesian.

Polar

• r: [0, inf)
• theta: [0, 2PI)

Spherical

• rho: [0, inf)
• theta: [0, 2PI)
• phi: [0, PI]

Cylindrical

• r: [0, inf)
• theta: [0, 2PI)
• z: (-inf, inf)

Usage

The library is meant to have static objects as it makes it easier to write equations which can be done by chaining then one after another:

VectorCartesian2D a = new VectorCartesian2D(1, 1);
VectorCartesian2D b = new VectorCartesian2D(2, 0);
VectorCartesian2D result = a.plus(b).minus(a.scalarMultiply(a.dot(b)).projectOnto(b));
//You can also do inline conversions
VectorPolar c = new VectorPolar(3, Math.PI);
VectorPolar result2 = c.plus(result.toPolar());

Future Considerations

1. The polar, spherical, and cylindrical coordinate systems can be further optimized by deriving faster mathematical solutions to computing things such as the dot product without converting the vector into cartesian first.
2. Adding polar vectors that have theta ranges from -PI to PI and 0 to 2PI (where 0 is at positive y axis) can be beneficial for encoder data as used in CTRE CanCoders.