Updated readability of the code.

[sixth-3d.git] / src / main / java / eu / svjatoslav / sixth / e3d / geometry / Point3D.java

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/geometry/Point3D.java b/src/main/java/eu/svjatoslav/sixth/e3d/geometry/Point3D.java
index e2c9868..1c8700a 100755 (executable)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/geometry/Point3D.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/geometry/Point3D.java
@@ -12,6 +12,7 @@ import static java.lang.Math.*;
 
 public class Point3D implements Cloneable {
 
+    // coordinates
     public double x, y, z;
 
     public Point3D() {
@@ -45,8 +46,9 @@ public class Point3D implements Cloneable {
     }
 
     /**
-     * Add other point to current point.
+     * Add other point to current point. Value of other point will not be changed.
      *
+     * @param otherPoint point to add.
      * @return current point.
      */
     public Point3D add(final Point3D otherPoint) {
@@ -60,13 +62,23 @@ public class Point3D implements Cloneable {
         return new Point3D(this);
     }
 
-    public Point3D clone(final Point3D parent) {
-        x = parent.x;
-        y = parent.y;
-        z = parent.z;
+    /**
+     * Copy coordinates from other point to current point. Value of other point will not be changed.
+     */
+    public Point3D clone(final Point3D otherPoint) {
+        x = otherPoint.x;
+        y = otherPoint.y;
+        z = otherPoint.z;
         return this;
     }
 
+    /**
+     * Set current point coordinates to the middle point between two other points.
+     *
+     * @param p1 first point.
+     * @param p2 second point.
+     * @return current point.
+     */
     public Point3D computeMiddlePoint(final Point3D p1, final Point3D p2) {
         x = (p1.x + p2.x) / 2d;
         y = (p1.y + p2.y) / 2d;
@@ -74,6 +86,9 @@ public class Point3D implements Cloneable {
         return this;
     }
 
+    /**
+     * @return true if current point coordinates are equal to zero.
+     */
     public boolean isZero() {
         return (x == 0) && (y == 0) && (z == 0);
     }
@@ -92,6 +107,9 @@ public class Point3D implements Cloneable {
 
     /**
      * Compute distance to another point.
+     *
+     * @param anotherPoint point to compute distance to.
+     * @return distance to another point.
      */
     public double getDistanceTo(final Point3D anotherPoint) {
         final double xDelta = x - anotherPoint.x;
@@ -101,10 +119,18 @@ public class Point3D implements Cloneable {
         return sqrt(((xDelta * xDelta) + (yDelta * yDelta) + (zDelta * zDelta)));
     }
 
+    /**
+     * @return length of current vector.
+     */
     public double getVectorLength() {
         return sqrt(((x * x) + (y * y) + (z * z)));
     }
 
+    /**
+     * Invert current point coordinates.
+     *
+     * @return current point.
+     */
     public Point3D invert() {
         x = -x;
         y = -y;
@@ -112,6 +138,15 @@ public class Point3D implements Cloneable {
         return this;
     }
 
+    /**
+     * Rotate current point around center point by angleXZ and angleYZ.
+     * <p>
+     * See also: <a href="https://marctenbosch.com/quaternions/">Let's remove Quaternions from every 3D Engine</a>
+     *
+     * @param center   center point.
+     * @param angleXZ angle around XZ axis.
+     * @param angleYZ angle around YZ axis.
+     */
     public void rotate(final Point3D center, final double angleXZ,
                        final double angleYZ) {
         final double s1 = sin(angleXZ);
@@ -135,12 +170,22 @@ public class Point3D implements Cloneable {
         z = z2 + center.z;
     }
 
+    /**
+     * Round current point coordinates to integer values.
+     */
     public void roundToInteger() {
         x = (int) x;
         y = (int) y;
         z = (int) z;
     }
 
+    /**
+     * Scale down current point by factor.
+     * All coordinates will be divided by factor.
+     *
+     * @param factor factor to scale by.
+     * @return current point.
+     */
     public Point3D scaleDown(final double factor) {
         x /= factor;
         y /= factor;
@@ -148,6 +193,13 @@ public class Point3D implements Cloneable {
         return this;
     }
 
+    /**
+     * Scale up current point by factor.
+     * All coordinates will be multiplied by factor.
+     *
+     * @param factor factor to scale by.
+     * @return current point.
+     */
     public Point3D scaleUp(final double factor) {
         x *= factor;
         y *= factor;
@@ -155,6 +207,12 @@ public class Point3D implements Cloneable {
         return this;
     }
 
+    /**
+     * Set current point coordinates to given values.
+     * @param x X coordinate.
+     * @param y Y coordinate.
+     * @param z Z coordinate.
+     */
     public void setValues(final double x, final double y, final double z) {
         this.x = x;
         this.y = y;
@@ -162,7 +220,7 @@ public class Point3D implements Cloneable {
     }
 
     /**
-     * Subtract other point from current point.
+     * Subtract other point from current point. Value of other point will not be changed.
      *
      * @return current point.
      */
@@ -179,6 +237,8 @@ public class Point3D implements Cloneable {
     }
 
     /**
+     * Translate current point along X axis by given increment.
+     *
      * @return current point.
      */
     public Point3D translateX(final double xIncrement) {
@@ -187,6 +247,8 @@ public class Point3D implements Cloneable {
     }
 
     /**
+     * Translate current point along Y axis by given increment.
+     *
      * @return current point.
      */
     public Point3D translateY(final double yIncrement) {
@@ -195,6 +257,8 @@ public class Point3D implements Cloneable {
     }
 
     /**
+     * Translate current point along Z axis by given increment.
+     *
      * @return current point.
      */
     public Point3D translateZ(final double zIncrement) {
@@ -213,7 +277,7 @@ public class Point3D implements Cloneable {
     }
 
     /**
-     * Resets point to 0 coordinate in X, Y and Z axis.
+     * Resets point coordinates to zero along all axes.
      *
      * @return current point.
      */