Package me.wobblyyyy.pathfinder.geometry

Class Point

java.lang.Object
me.wobblyyyy.pathfinder.geometry.Point
Direct Known Subclasses:
HeadingPoint
public class Point
extends java.lang.Object
The most simple geometry of all - a singular point.

Now, in case you have serious brain damage, a point is just an X and a Y value put together. I'm assuming you don't have serious brain damage, so you can continue reading. Have fun.

Points are the core of any of the geometry in this library. Everything in this class should (hopefully) be pretty well-documented. Also, I'd like to suggest to you that you check out the static methods in the latter half of this file - they're incredibly useful for point manipulation.

Although points are incredibly simple as a concept - I mean, come on, man. It's a point! How hard can point things really be? Not very is your answer.

Since:
0.1.0
Author:
Colin Robertson

  • Field Summary

    Fields
    Modifier and Type Field Description
    private double x
    The point's X value.
    private double y
    The point's Y value.

  • Constructor Summary

    Constructors
    Constructor Description
    Point​(double x, double y)
    Create a new point.

  • Method Summary

    Modifier and Type Method Description
    static Point add​(Point a, Point b)
    Add two points together to form another point.
    static double angleOfDeg​(HeadingPoint a, HeadingPoint b)
    Get the angle from point A to point B.
    static double angleOfRad​(HeadingPoint a, HeadingPoint b)
    Get the angle from point A to point B.
    static Point average​(Point... points)
    Blend several points together.
    static Point blend​(Point a, Point b)
    Blend (average) two points together to form another point.
    Point copy()
    Creates a copied point.
    double getTheta()
    Get the theta measurement, from the origin of the plane, to this point.
    double getX()
    Get the point's X value.
    double getY()
    Get the point's Y value.
    static boolean isSame​(Point a, Point b)
    Are two points exactly identical?
    void scale​(double scale)
    Scale a point based a given value.
    void scale​(double xScale, double yScale)
    Scale a point based on two scale factors.
    static Point scale​(Point a, double multiplier)
    Scale a point upwards or downwards by a specific factor.
    static Point scale​(Point a, double xMultiplier, double yMultiplier)
    Scale the X and Y values of a point separately.
    static Point scaleX​(Point a, double multiplier)
    Scale only the X value of a point.
    static Point scaleY​(Point a, double multiplier)
    Scale only the Y value of a point.
    java.lang.String toString()
    Get the string value of the point.
    HeadingPoint withHeading()
    Get a clone of this point with a heading of 0 degrees.
    HeadingPoint withHeading​(double heading)
    Get a clone of this instanced point with a new heading.
    static HeadingPoint withHeading​(Point a, double heading)
    Get a clone of this point with a heading.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • x

      private double x
      The point's X value.

    • y

      private double y
      The point's Y value.

  • Constructor Details

    • Point

      public Point​(double x, double y)
      Create a new point.

      Units aren't important for field-mapping and geometry, as all units are relative. However, I'd strongly suggest that you keep everything in inches. I'm not suggesting this because I feel like it - rather, if you don't use inches, some of the critical pathfinding code won't work.

      Parameters:
      x - the point's X value.
      y - the point's Y value.

  • Method Details

    • getX

      public double getX()
      Get the point's X value.

      Points are final - this value should not ever change after it has been initialized. If you'd like to modify a point's values, you can create another point or use one of the static methods in this file.

      Returns:
      the point's X value.

    • getY

      public double getY()
      Get the point's Y value.

      Points are final - this value should not ever change after it has been initialized. If you'd like to modify a point's values, you can create another point or use one of the static methods in this file.

      Returns:
      the point's Y value.

    • getTheta

      public double getTheta()
      Get the theta measurement, from the origin of the plane, to this point.

      This is essentially a fancy wrapper for Math.atan2, which, in case you weren't aware, calculates the angle a point is at based on that point's tangent. Although the method returns a measurement in radians, it's converted to degrees prior to being returned.

      Returns:
      the theta measurement, in degrees.

    • scale

      public void scale​(double scale)
      Scale a point based a given value.
      Parameters:
      scale - the point's scale factor.

    • scale

      public void scale​(double xScale, double yScale)
      Scale a point based on two scale factors.
      Parameters:
      xScale - the X axis scale factor.
      yScale - the Y axis scale factor.

    • blend

      public static Point blend​(Point a, Point b)
      Blend (average) two points together to form another point.
      Parameters:
      a - the first of the two points.
      b - the second of the two points.
      Returns:
      the result blended point.

    • add

      public static Point add​(Point a, Point b)
      Add two points together to form another point.

      This is NOT the same as blending! Blending is averaging, whereas this method is simply addition.

      Parameters:
      a - one of the two points.
      b - one of the two points.
      Returns:
      the sum of the two points.

    • scale

      public static Point scale​(Point a, double multiplier)
      Scale a point upwards or downwards by a specific factor.

      This method does not independently scale the X and Y values - to do that, you can take a look at any of these methods:

      Parameters:
      a - the point to be scaled.
      multiplier - the factor to scale the point by.
      Returns:
      a new, scaled, point.

    • scale

      public static Point scale​(Point a, double xMultiplier, double yMultiplier)
      Scale the X and Y values of a point separately.

      If you're interested in scaling these axes uniformly, you can use the simpler scale(Point, double) method.

      Parameters:
      a - the point to be scaled.
      xMultiplier - the value by which the X value is multiplied.
      yMultiplier - the value by which the Y value is multiplier.
      Returns:
      a newly-scaled value.

    • scaleX

      public static Point scaleX​(Point a, double multiplier)
      Scale only the X value of a point.

      If you'd like to scale both axes at the same time, you can check out either of these two methods.

      Parameters:
      a - the point to be scaled.
      multiplier - the value by which the point should be scaled by.
      Returns:
      a newly-scaled point.

    • scaleY

      public static Point scaleY​(Point a, double multiplier)
      Scale only the Y value of a point.

      If you'd like to scale both axes at the same time, you can check out either of these two methods.

      Parameters:
      a - the point to be scaled.
      multiplier - the value by which the point should be scaled by.
      Returns:
      a newly-scaled point.

    • average

      public static Point average​(Point... points)
      Blend several points together.

      There's no weight or bias to this - each of the inputted points is balanced evenly with all of the other points.

      Parameters:
      points - the points to blend together.
      Returns:
      the blended/averaged points.

    • toString

      public java.lang.String toString()
      Get the string value of the point.

      Although Java's default toString method is quite lovely, it doesn't actually do a great job of converting a point to a string. So, all we have to do is override it, and we're all good! Yay!

      Overrides:
      toString in class java.lang.Object
      Returns:
      the point, expressed as a string.

    • isSame

      public static boolean isSame​(Point a, Point b)
      Are two points exactly identical?

      Points are considered to be identical or non-identical based solely on the point's X and Y values. If they're all the same, the points are identical. If they're not, they're not identical.

      Parameters:
      a - the first of the two points.
      b - the second of the two points.
      Returns:
      whether or not the points are identical.

    • withHeading

      public static HeadingPoint withHeading​(Point a, double heading)
      Get a clone of this point with a heading.
      Parameters:
      a - the point to clone.
      heading - the heading the point should have.
      Returns:
      a new heading point based on this one.

    • withHeading

      public HeadingPoint withHeading()
      Get a clone of this point with a heading of 0 degrees.
      Returns:
      a clone of this point with a heading of 0 degrees.

    • withHeading

      public HeadingPoint withHeading​(double heading)
      Get a clone of this instanced point with a new heading.
      Parameters:
      heading - the new heading to add.
      Returns:
      a HeadingPoint based off this point.

    • copy

      public Point copy()
      Creates a copied point.

      This is a DEEP, not a SHALLOW clone. Deep clones are entirely new objects - no shared hash codes, etc. Shallow clones aren't new objects. This is essentially the clone() method, but cooler.

      Returns:
      a cloned version of this point.

    • angleOfRad

      public static double angleOfRad​(HeadingPoint a, HeadingPoint b)
      Get the angle from point A to point B. This method inversely subtracts the two points and uses the Math.atan2(double, double) method to determine the angle between them.

      The angle between two points is defined as follows: atan2(y2 - y1, x2 - x1)

      Parameters:
      a - the first of the two points.
      b - the second of the two points.
      Returns:
      the angle between the two points, notated in radians.

    • angleOfDeg

      public static double angleOfDeg​(HeadingPoint a, HeadingPoint b)
      Get the angle from point A to point B. This method inversely subtracts the two points and uses the Math.atan2(double, double) method to determine the angle between them.
      Parameters:
      a - the first of the two points.
      b - the second of the two points.
      Returns:
      the angle between the two points, notated in radians.