Fixed git clone URL

[sixth-3d.git] / src / main / java / eu / svjatoslav / sixth / e3d / gui / UserRelativityTracker.java

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java b/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
index d183325..d491b0f 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
@@ -1,64 +1,99 @@
 /*
- * Sixth 3D engine. Copyright ©2012-2018, Svjatoslav Agejenko, svjatoslav@svjatoslav.eu
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of version 3 of the GNU Lesser General Public License
- * or later as published by the Free Software Foundation.
- *
+ * Sixth 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
  */
-
-
 package eu.svjatoslav.sixth.e3d.gui;
 
-import eu.svjatoslav.sixth.e3d.geometry.GeometryCoordinate;
 import eu.svjatoslav.sixth.e3d.geometry.Point3D;
-import eu.svjatoslav.sixth.e3d.geometry.TransformPipe;
+import eu.svjatoslav.sixth.e3d.math.TransformsStack;
+import eu.svjatoslav.sixth.e3d.math.Vertex;
+
+/**
+ * Tracks the position of the user in the 3D space.
+ * <p>
+ * It can be used to determine the angle between the user and the object.
+ * Also, it can be used to determine the distance between the user and the object.
+ */
 
 public class UserRelativityTracker {
 
-    public final static int minimalSliceFactor = 5;
-    public GeometryCoordinate center = new GeometryCoordinate();
-    public GeometryCoordinate right;
-    public GeometryCoordinate down;
+    private final static int minimalSliceFactor = 5;
+
+    /**
+     * Points to 0, 0, 0 in object own relative space.
+     */
+    public Vertex center = new Vertex();
+
+    /**
+     * Points to 10, 0, 0 in object own relative space if orientation tracking is enabled.
+     * It is used to determine the angle between the user and the object.
+     */
+    public Vertex right;
+
+    /**
+     * Points to 0, 10, 0 in object own relative space if orientation tracking is enabled.
+     * It is used to determine the angle between the user and the object.
+     */
+    public Vertex down;
 
     public UserRelativityTracker() {
 
     }
 
-    public void analyze(final TransformPipe transformPipe,
+    public void analyze(final TransformsStack transformPipe,
                         final RenderingContext renderingContext) {
 
-        center.transform(transformPipe, renderingContext);
+        center.calculateLocationRelativeToViewer(transformPipe, renderingContext);
 
-        if (right != null) {
-            right.transform(transformPipe, renderingContext);
-            down.transform(transformPipe, renderingContext);
+        if (right != null) { // If orientation tracking is enabled.
+            right.calculateLocationRelativeToViewer(transformPipe, renderingContext);
+            down.calculateLocationRelativeToViewer(transformPipe, renderingContext);
         }
     }
 
+    /**
+     * Initializes the orientation tracking.
+     * Orientation tracking is used to determine the angle between the user and the object.
+     * Orientation tracking is disabled by default and it is optional.
+     */
     public void enableOrientationTracking() {
-        right = new GeometryCoordinate(new Point3D(10, 0, 0));
-        down = new GeometryCoordinate(new Point3D(0, 10, 0));
+        right = new Vertex(new Point3D(10, 0, 0));
+        down = new Vertex(new Point3D(0, 10, 0));
     }
 
+    /**
+     * Calculates the angle between the user and the object in the XY plane.
+     * @return the angle between the user and the object in the XY plane.
+     */
     public double getAngleXY() {
         return center.transformedCoordinate
                 .getAngleXY(down.transformedCoordinate);
     }
 
+    /**
+     * Calculates the angle between the user and the object in the XZ plane.
+     * @return the angle between the user and the object in the XZ plane.
+     */
     public double getAngleXZ() {
         return center.transformedCoordinate
                 .getAngleXZ(right.transformedCoordinate);
     }
 
+    /**
+     * Calculates the angle between the user and the object in the YZ plane.
+     * @return the angle between the user and the object in the YZ plane.
+     */
     public double getAngleYZ() {
         return center.transformedCoordinate
                 .getAngleYZ(down.transformedCoordinate);
     }
 
+    /**
+     * Calculates the distance between the user and the object.
+     * Distance to the user can be used to determine object detail level.
+     */
     public double getDistanceToUser() {
-        return center.transformedCoordinate
-                .getDistanceTo(Point3D.ZERO);
+        return center.transformedCoordinate.getVectorLength();
     }
 
     public double proposeSliceFactor() {