Merge pull request #1 from HexagonNico/dev

Refine work on quaternions

Readme.md

@@ -172,7 +172,7 @@ operations are called, it can be used safely in a multithreaded application.
 ### sbt
 
 ```
-libraryDependencies += "io.github.hexagonnico" % "vecmatlib" % "2.3"
+libraryDependencies += "io.github.hexagonnico" % "vecmatlib" % "2.3.1"
 ```
 
 ### Maven
@@ -181,14 +181,14 @@ libraryDependencies += "io.github.hexagonnico" % "vecmatlib" % "2.3"
 <dependency>
     <groupId>io.github.hexagonnico</groupId>
     <artifactId>vecmatlib</artifactId>
-    <version>2.3</version>
+    <version>2.3.1</version>
 </dependency>
 ```
 
 ### Gradle
 
 ```
-implementation 'io.github.hexagonnico:vecmatlib:2.3'
+implementation 'io.github.hexagonnico:vecmatlib:2.3.1'
 ```
 
 ## Contributing

build.sbt

@@ -1,4 +1,4 @@
-ThisBuild / version := "2.3"
+ThisBuild / version := "2.3.1"
 
 ThisBuild / scalaVersion := "2.13.12"
 

src/main/scala/io/github/hexagonnico/vecmatlib/matrix/Mat3d.scala

@@ -1,5 +1,6 @@
 package io.github.hexagonnico.vecmatlib.matrix
 
+import io.github.hexagonnico.vecmatlib.quaternion.QuaternionD
 import io.github.hexagonnico.vecmatlib.vector.{Vec2d, Vec3d}
 
 /**
@@ -248,6 +249,22 @@ object Mat3d {
    */
   def rotation(x: Double, y: Double, z: Double): Mat3d = rotationX(x) * rotationY(y) * rotationZ(z)
 
+  /**
+   * Returns a 3x3 rotation matrix with the given rotation.
+   *
+   * @param v Vector representing the rotation in radians
+   * @return A 3x3 rotation matrix
+   */
+  def rotation(v: Vec3d): Mat3d = this.rotation(v.x, v.y, v.z)
+
+  /**
+   * Returns a 3x3 rotation matrix with the rotation represented by the given quaternion.
+   *
+   * @param q The rotation quaternion
+   * @return A 3x3 rotation matrix
+   */
+  def rotation(q: QuaternionD): Mat3d = q.rotationMatrix
+
   /**
    * Returns a 3x3 scaling matrix with the given scale.
    *

src/main/scala/io/github/hexagonnico/vecmatlib/matrix/Mat3f.scala

@@ -1,5 +1,6 @@
 package io.github.hexagonnico.vecmatlib.matrix
 
+import io.github.hexagonnico.vecmatlib.quaternion.QuaternionF
 import io.github.hexagonnico.vecmatlib.vector.{Vec2f, Vec3f}
 
 /**
@@ -246,7 +247,23 @@ object Mat3f {
    * @param z Rotation angle in radians on the z axis
    * @return A 3x3 rotation matrix
    */
-  def rotation(x: Float, y: Float, z: Float): Mat3f = rotationX(x) * rotationY(y) * rotationZ(z)
+  def rotation(x: Float, y: Float, z: Float): Mat3f = this.rotationX(x) * this.rotationY(y) * this.rotationZ(z)
+
+  /**
+   * Returns a 3x3 rotation matrix with the given rotation.
+   *
+   * @param v Vector representing the rotation in radians
+   * @return A 3x3 rotation matrix
+   */
+  def rotation(v: Vec3f): Mat3f = this.rotation(v.x, v.y, v.z)
+
+  /**
+   * Returns a 3x3 rotation matrix with the rotation represented by the given quaternion.
+   *
+   * @param q The rotation quaternion
+   * @return A 3x3 rotation matrix
+   */
+  def rotation(q: QuaternionF): Mat3f = q.rotationMatrix
 
   /**
    * Returns a 3x3 scaling matrix with the given scale.

src/main/scala/io/github/hexagonnico/vecmatlib/quaternion/Quaternion.scala

@@ -5,15 +5,16 @@ import io.github.hexagonnico.vecmatlib.vector.VecAbstract
 /**
  * Abstract class with quaternion operations.
  *
- * @tparam Q The quaternion class extending this one
+ * @tparam Q The quaternion class extending this one.
+ * @tparam V The 3D vector of the same type as this quaternion.
  */
 abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
 
   /**
    * Returns the sum between this quaternion and the given one.
    *
-   * @param q The quaternion to add
-   * @return The sum of this quaternion and the given one
+   * @param q The quaternion to add.
+   * @return The sum of this quaternion and the given one.
    */
   def +(q: Q): Q
 
@@ -22,15 +23,15 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * This method can be used in place of the '+' operator for better interoperability with Java.
    *
-   * @param q The quaternion to add
-   * @return The sum of this quaternion and the given one
+   * @param q The quaternion to add.
+   * @return The sum of this quaternion and the given one.
    */
   def plus(q: Q): Q = this + q
 
   /**
    * Returns the additive inverse of this quaternion.
    *
-   * @return The additive inverse of this quaternion
+   * @return The additive inverse of this quaternion.
    */
   def unary_-(): Q
 
@@ -46,8 +47,8 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
   /**
    * Returns the subtraction between the given quaternion and this one.
    *
-   * @param q The quaternion to subtract
-   * @return The subtraction of the given quaternion from this one
+   * @param q The quaternion to subtract.
+   * @return The subtraction of the given quaternion from this one.
    */
   def -(q: Q): Q = this + (-q)
 
@@ -56,16 +57,16 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * This method can be used in place of the '-' operator for better interoperability with Java.
    *
-   * @param q The quaternion to subtract
-   * @return The subtraction of the given quaternion from this one
+   * @param q The quaternion to subtract.
+   * @return The subtraction of the given quaternion from this one.
    */
   def minus(q: Q): Q = this - q
 
   /**
    * Returns the product between this quaternion and the given one as defined by the Hamilton product.
    *
-   * @param q The second operand of the multiplication
-   * @return The product between this quaternion and the given one
+   * @param q The second operand of the multiplication.
+   * @return The product between this quaternion and the given one.
    */
   def *(q: Q): Q
 
@@ -74,29 +75,30 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * This method can be used in place of the '*' operator for better interoperability with Java.
    *
-   * @param q The second operand of the multiplication
-   * @return The product between this quaternion and the given one
+   * @param q The second operand of the multiplication.
+   * @return The product between this quaternion and the given one.
    */
   def multiply(q: Q): Q = this * q
 
   /**
    * Returns the conjugate of this quaternion.
    * The conjugate of a quaternion `w + xi + yj + zk` is the quaternion `w - xi - yj - zk`.
    *
-   * @return The conjugate of this quaternion
+   * @return The conjugate of this quaternion.
    */
   def conjugate: Q
 
   /**
    * Returns the length (or norm) of this quaternion.
    *
-   * @return The norm of this quaternion
+   * @return The norm of this quaternion.
    */
   def length: Double
 
   /**
    * Returns this quaternion as a unit quaternion.
-   * That is, this quaternion divided by its norm or [[length]].
+   * That is, a quaternion of norm (or [[length]]) 1.
+   * Obtained by dividing this quaternion by its [[length]].
    *
    * @return This quaternion as a unit quaternion
    */
@@ -107,15 +109,15 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * The same quaternion can be obtained with `1.0 / q`.
    *
-   * @return The inverse of this quaternion
+   * @return The inverse of this quaternion.
    */
   def inverse: Q
 
   /**
    * Returns the product of this quaternion by the [[inverse]] of the given one.
    *
-   * @param q The second operand of the division
-   * @return The product of this quaternion by the inverse of the given one
+   * @param q The second operand of the division.
+   * @return The product of this quaternion by the inverse of the given one.
    */
   def /(q: Q): Q = this * q.inverse
 
@@ -124,22 +126,33 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * This method can be used in place of the '/' operator for better interoperability with Java.
    *
-   * @param q The second operand of the division
-   * @return The product of this quaternion by the inverse of the given one
+   * @param q The second operand of the division.
+   * @return The product of this quaternion by the inverse of the given one.
    */
   def divide(q: Q): Q = this / q
 
+  /**
+   * Raises this quaternion to the power of the given exponent.
+   *
+   * A quaternion raised to the power of 0 is the identity quaternion.
+   * A quaternion raised to a negative power is equal to its inverse raised to the additive inverse of the exponent.
+   *
+   * @param t The exponent.
+   * @return This quaternion raised to the power of the given exponent.
+   */
+  def pow(t: Int): Q
+
   /**
    * Returns the exponential of this quaternion.
    *
-   * @return The exponential of this quaternion
+   * @return The exponential of this quaternion.
    */
   def exp: Q
 
   /**
    * Returns the logarithm of this quaternion.
    *
-   * @return The logarithm of this quaternion
+   * @return The logarithm of this quaternion.
    */
   def log: Q
 
@@ -148,7 +161,9 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * The result is undefined if this quaternion is not [[normalized]].
    *
-   * @return This quaternion's rotation in the form of euler angles
+   * TODO: Specify rotation order
+   *
+   * @return This quaternion's rotation in the form of euler angles.
    */
   def euler: V
 
@@ -157,24 +172,24 @@ abstract class Quaternion[Q <: Quaternion[Q, V], V <: VecAbstract[V]] {
    *
    * The result is undefined if this quaternion is not [[normalized]].
    *
-   * @return The angle of the rotation represented by this unit quaternion
+   * @return The angle of the rotation represented by this unit quaternion.
    */
   def angle: Double
 
   /**
    * Returns the vector part of this quaternion.
    * The vector part of a quaternion `w + xi + yj + zk` is the vector `(x, y, z)`.
    *
-   * Normalize this vector to get the rotation axis of the quaternion.
-   *
-   * @return
+   * @return The vector part of this quaternion.
    */
   def vector: V
 
   /**
-   * Returns that is, this quaternion divided by its norm or [[length]].
+   * Returns the spherical linear interpolation between this quaternion and the given one.
    *
-   * @return A unit quaternion
+   * @param to The second quaternion.
+   * @param weight Interpolation weight.
+   * @return The spherical linear interpolation between this quaternion and the given one
    */
   def slerp(to: Q, weight: Double): Q
 }