Add documentation

Author: tmthecoder

LICENSE

@@ -0,0 +1,7 @@
+Copyright 2020 Tejas Mehta <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,66 @@
+## Odometry Core
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This is a library made to handle the core mathematical calculations for three wheel Odometry.
+
+This library requires either a value in encoder ticks, paired with the counts per revolution per encoder, or an inch value for each encoder to be given
+
+## Installation (Gradle)
+In order to use this library, paste the following code under your ``allprojects/repositories``:
+
+```
+allprojects {
+    repositories {
+        jcenter()
+        maven { url "https://jitpack.io" }  //Add this line
+    }
+}
+``` 
+
+Then place the following line under your ```dependencies```:
+```
+dependencies {
+    implementation 'com.github.tmthecoder:OdometryCore:1.0.0'
+}
+```
+## Installation (JAR)
+
+Alternatively, you can use the provided JAR in the releases section under the latest released version
+
+## Usage
+
+**Library Initialization:**
+```
+OdometryCore.initialize(cpr, diameter, leftOffet, rightOffset, frontBackOffset);
+```
+The parameters seen are:
+- cpr: The counts per revolution for the encoders you are using
+- diameter: The diameter of the wheels on the encoder
+- leftOffset: The offset of the left wheel from the center of the robot (only horizontal offset)
+- rightOffset: The offset of the right wheel from the center of the robot (only horizontal offset)
+- frontBackOffset: The offset of the front or back encoder wheel (only vertical offset)
+
+**Position Tracking:**
+
+After initializing, the robot's position can be found using the following code:
+```               
+EncoderPositions encoderPositions = new EncoderPositions(leftPosition, rightPosition, frontBackPosition);
+OdometryPosition position = OdometryCore.getInstance().getCurrentPosition(encoderPositions);
+```
+The parameters seen are: 
+- leftPosition: The left encoder's position in ticks
+- rightPosition: The right encoder's position in ticks
+- frontBackPosition: The front or back encoder's position in ticks
+
+The position tracking code should be run on a loop with as small an interval as possible, and if possible on a separate thread
+
+## Features and Bugs
+Please file feature requests and bugs at the [issue tracker].
+
+[issue tracker]: https://github.com/tmthecoder/OdometryCore/issues
+
+## Licensing
+
+OdometryCore is Licensed under the [MIT License] 
+
+[MIT License]: https://github.com/tmthecoder/OdometryCore/blob/main/LICENSE

src/main/java/com/tejasmehta/OdometryCore/OdometryCore.java

@@ -5,6 +5,12 @@
 import com.tejasmehta.OdometryCore.localization.OdometryPosition;
 import com.tejasmehta.OdometryCore.math.CoreMath;
 
+/**
+ * @author Tejas Mehta
+ * Made on Wednesday, November 04, 2020
+ * File Name: Odometrycore
+ * The main class to wrap over all odometry calculations
+ */
 public class OdometryCore {
 
     private final double wheelDiameter;
@@ -18,6 +24,14 @@ public class OdometryCore {
     private double frontBackInches = 0;
     private OdometryPosition position = new OdometryPosition(0, 0, 0, HeadingUnit.RADIANS);
 
+    /**
+     * Private constructor for local instance construction
+     * @param cpr - The counts per rotation for the encoders
+     * @param wheelDiameter - The encoder wheel's diameter (in inches)
+     * @param leftOffset - The left encoder's offset from the center (in inches)
+     * @param rightOffset - The right wheel's offset from the center (in inches)
+     * @param frontBackOffset - The front or back wheel's offset from the center (in inches)
+     */
     private OdometryCore(double cpr, double wheelDiameter, double leftOffset, double rightOffset, double frontBackOffset) {
         this.wheelDiameter = wheelDiameter;
         this.cpr = cpr;
@@ -26,20 +40,41 @@ private OdometryCore(double cpr, double wheelDiameter, double leftOffset, double
         this.frontBackOffset = frontBackOffset;
     }
 
-
+    /**
+     * The static instance getter
+     * @throws IllegalArgumentException if there is no instance made
+     * @return - The current instance of OdometryCore
+     */
     public static OdometryCore getInstance() {
         if (instance == null) throw new IllegalArgumentException("Please initialize OdometryCore with OdometryCore.initialize(cpr, wheelDiameter, leftOffset, rightOffset, frontBackOffset)");
         return instance;
     }
 
+    /**
+     * A method to initialize the static OdometryCore instance
+     * @param cpr - The counts per rotation for the encoders
+     * @param wheelDiameter - The encoder wheel's diameter (in inches)
+     * @param leftOffset - The left encoder's offset from the center (in inches)
+     * @param rightOffset - The right wheel's offset from the center (in inches)
+     * @param frontBackOffset - The front or back wheel's offset from the center (in inches)
+     */
     public static void initialize(double cpr, double wheelDiameter, double leftOffset, double rightOffset, double frontBackOffset) {
         instance = new OdometryCore(cpr, wheelDiameter, leftOffset, rightOffset, frontBackOffset);
     }
 
+    /**
+     * A checker to see whether the core is initialized
+     * @return - A boolean signifying whether the core is initialized
+     */
     public static boolean isInitialized() {
         return instance != null;
     }
 
+    /**
+     * A method to get the current position using three wheel odometry
+     * @param positions - The robot's three encoder's positions
+     * @return - The Position of the robot with an x, y, and heading
+     */
     public OdometryPosition getCurrentPosition(EncoderPositions positions) {
         double newLeftInches = CoreMath.ticksToInches(positions.getLeftPosition(), cpr, wheelDiameter);
         double newRightInches = CoreMath.ticksToInches(positions.getRightPosition(), cpr, wheelDiameter);

src/main/java/com/tejasmehta/OdometryCore/localization/EncoderPositions.java

@@ -1,37 +1,48 @@
+package com.tejasmehta.OdometryCore.localization;
+
 /****
- * Made by Tejas Mehta
+ * @author Tejas Mehta
  * Made on Wednesday, November 11, 2020
- * File Name: EncoderTicks
- * Package: com.tejasmehta.OdometryCore.localization
+ * File Name: EncoderPositions
+ * A class to unify all three encoder positions used in the core calculations
  */
-package com.tejasmehta.OdometryCore.localization;
-
 public class EncoderPositions {
     private final double leftPosition;
     private final double rightPosition;
     private final double frontBackPosition;
 
     /**
-     * A wrapper for encoder positions
-     * @param leftPosition
-     * @param rightPosition
-     * @param frontBackPosition
+     * The constructor for the encoder positions class
+     * @param leftPosition - The left encoder's position in ticks
+     * @param rightPosition - The right encoder's position in ticks
+     * @param frontBackPosition - The Front or back encoder's position in ticks
      */
     public EncoderPositions(double leftPosition, double rightPosition, double frontBackPosition) {
         this.leftPosition = leftPosition;
         this.rightPosition = rightPosition;
         this.frontBackPosition = frontBackPosition;
     }
 
-
+    /**
+     * A method to get the left encoder's position
+     * @return - The left encoder's position (in ticks)
+     */
     public double getLeftPosition() {
         return leftPosition;
     }
 
+    /**
+     * A method to get the right encoder's position
+     * @return - The right encoder's position (in ticks)
+     */
     public double getRightPosition() {
         return rightPosition;
     }
 
+    /**
+     * A method to get the front or back encoder's position
+     * @return - The front or back encoder's position (in ticks)
+     */
     public double getFrontBackPosition() {
         return frontBackPosition;
     }

src/main/java/com/tejasmehta/OdometryCore/localization/HeadingUnit.java

@@ -1,17 +1,11 @@
-/****
- * Made by Tejas Mehta
- * Made on Wednesday, November 11, 2020
- * File Name: HeadingUnit
- * Package: org.firstinspires.ftc.teamcode.testCode.odometryCoreTest.localization*/
 package com.tejasmehta.OdometryCore.localization;
 
 /****
- * Made by Tejas Mehta
+ * @author Tejas Mehta
  * Made on Wednesday, November 04, 2020
  * File Name: OdometryPosition
- * Package: com.tejasmehta.com.tejasmehta.OdometryCore.localization
+ * An emun for the heading unit used in the OdometryPosition
  */
-
 public enum HeadingUnit {
     DEGREES,
     RADIANS

src/main/java/com/tejasmehta/OdometryCore/localization/OdometryPosition.java

@@ -1,36 +1,59 @@
+package com.tejasmehta.OdometryCore.localization;
+
 /****
- * Made by Tejas Mehta
- * Made on Wednesday, November 12, 2020
+ * @author  Tejas Mehta
+ * Made on Thursday, November 12, 2020
  * File Name: EncoderTicks
- * Package: com.tejasmehta.OdometryCore.localization
+ * A class to store the Odometry position in the format of an x coordinate, a y coordinate, and an angle measure
  */
-package com.tejasmehta.OdometryCore.localization;
-
 public class OdometryPosition {
     private final double x;
     private final double y;
     private final double heading;
     private final HeadingUnit unit;
 
+    /**
+     * The constructor for the OdometryPosition class
+     * @param x - The x value on a cartesian plane (in inches)
+     * @param y - The y value on a cartesian plane (in inches)
+     * @param heading - The robot's current heading (in degrees or radians)
+     * @param unit - The unit for the heading (either HeadingUnit.degrees or HeadingUnit.radians)
+     */
     public OdometryPosition(double x, double y, double heading, HeadingUnit unit) {
         this.x = x;
         this.y = y;
         this.heading = heading;
         this.unit = unit;
     }
 
+    /**
+     * A getter for the x value
+     * @return - The robot's x value (in inches)
+     */
     public double getX() {
         return x;
     }
 
+    /**
+     * A getter for the y value
+     * @return - The robot's y value (in inches)
+     */
     public double getY() {
         return y;
     }
 
+    /**
+     * A getter for the robot's heading
+     * @return - The robot's heading (in degrees)
+     */
     public double getHeadingDegrees() {
         return unit == HeadingUnit.DEGREES ? heading : Math.toDegrees(heading);
     }
 
+    /**
+     * A getter for the robot's heading
+     * @return - The robot's heading (in radians)
+     */
     public double getHeadingRadians() {
         return unit == HeadingUnit.RADIANS ? heading : Math.toDegrees(heading);
     }

src/main/java/com/tejasmehta/OdometryCore/math/CartesianCoordinate.java

@@ -1,15 +1,20 @@
+package com.tejasmehta.OdometryCore.math;
+
 /****
- * Made by Tejas Mehta
+ * @author Tejas Mehta
  * Made on Wednesday, November 04, 2020
  * File Name: LocalCoordinate
- * Package: com.tejasmehta.OdometryCore.math
+ * A class to signify a cartesian coordinate and to simplify polar and cartesian operations
  */
-package com.tejasmehta.OdometryCore.math;
-
 public class CartesianCoordinate {
     private final double x;
     private final double y;
 
+    /**
+     * A method to create a CartesianCoordinate from a given PolarCoordinate
+     * @param polar - The polar coordinate to convert to a cartesian one
+     * @return - The cartesian coordinate of the polar value
+     */
     public static CartesianCoordinate fromPolar(PolarCoordinate polar) {
         double r = polar.getR();
         double theta = polar.getTheta();
@@ -18,19 +23,36 @@ public static CartesianCoordinate fromPolar(PolarCoordinate polar) {
         return new CartesianCoordinate(x, y);
     }
 
+    /**
+     * The constructor for a the CartesianCoordinate class
+     * @param x - The x value of the coordinate
+     * @param y - The y value of the coordinate
+     */
     public CartesianCoordinate(double x, double y) {
         this.x = x;
         this.y = y;
     }
 
+    /**
+     * A getter for the coordinate's x value
+     * @return - the coordinate's x value
+     */
     public double getX() {
         return x;
     }
 
+    /**
+     * A getter for the coordinate's y value
+     * @return - the coordinate's y value
+     */
     public double getY() {
         return y;
     }
 
+    /**
+     * Method to handle toString calls on the object
+     * @return - A string with the coordinates x and y values
+     */
     @Override
     public String toString() {
         return "CartesianCoordinate{" +