Class Coordinate

  • All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Comparable<Coordinate>
    Direct Known Subclasses:
    CoordinateXY, CoordinateXYM, CoordinateXYZM

    public class Coordinate
    extends java.lang.Object
    implements java.lang.Comparable<Coordinate>, java.lang.Cloneable, java.io.Serializable
    A lightweight class used to store coordinates on the 2-dimensional Cartesian plane.

    It is distinct from Point, which is a subclass of Geometry. Unlike objects of type Point (which contain additional information such as an envelope, a precision model, and spatial reference system information), a Coordinate only contains ordinate values and accessor methods.

    Coordinates are two-dimensional points, with an additional Z-ordinate. If an Z-ordinate value is not specified or not defined, constructed coordinates have a Z-ordinate of NaN (which is also the value of NULL_ORDINATE). The standard comparison functions ignore the Z-ordinate. Apart from the basic accessor functions, JTS supports only specific operations involving the Z-ordinate.

    Implementations may optionally support Z-ordinate and M-measure values as appropriate for a CoordinateSequence. Use of getZ() and getM() accessors, or getOrdinate(int) are recommended.

    Version:
    1.16
    See Also:
    Serialized Form
    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  Coordinate.DimensionalComparator
      Compares two Coordinates, allowing for either a 2-dimensional or 3-dimensional comparison, and handling NaN values correctly.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int M
      Standard ordinate index value for, where M is 3.
      static double NULL_ORDINATE
      The value used to indicate a null or missing ordinate value.
      double x
      The x-ordinate.
      static int X
      Standard ordinate index value for, where X is 0
      double y
      The y-ordinate.
      static int Y
      Standard ordinate index value for, where Y is 1
      double z
      The z-ordinate.
      static int Z
      Standard ordinate index value for, where Z is 2.
    • Constructor Summary

      Constructors 
      Constructor Description
      Coordinate()
      Constructs a Coordinate at (0,0,NaN).
      Coordinate​(double x, double y)
      Constructs a Coordinate at (x,y,NaN).
      Coordinate​(double x, double y, double z)
      Constructs a Coordinate at (x,y,z).
      Coordinate​(Coordinate c)
      Constructs a Coordinate having the same (x,y,z) values as other.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.Object clone()  
      int compareTo​(Coordinate o)
      Compares this Coordinate with the specified Coordinate for order.
      Coordinate copy()
      Creates a copy of this Coordinate.
      double distance​(Coordinate c)
      Computes the 2-dimensional Euclidean distance to another location.
      double distance3D​(Coordinate c)
      Computes the 3-dimensional Euclidean distance to another location.
      boolean equalInZ​(Coordinate c, double tolerance)
      Tests if another coordinate has the same value for Z, within a tolerance.
      boolean equals​(java.lang.Object other)
      Returns true if other has the same values for the x and y ordinates.
      boolean equals2D​(Coordinate other)
      Returns whether the planar projections of the two Coordinates are equal.
      boolean equals2D​(Coordinate c, double tolerance)
      Tests if another Coordinate has the same values for the X and Y ordinates, within a specified tolerance value.
      boolean equals3D​(Coordinate other)
      Tests if another coordinate has the same values for the X, Y and Z ordinates.
      double getM()
      Retrieves the value of the measure, if present.
      double getOrdinate​(int ordinateIndex)
      Gets the ordinate value for the given index.
      double getX()
      Retrieves the value of the X ordinate.
      double getY()
      Retrieves the value of the Y ordinate.
      double getZ()
      Retrieves the value of the Z ordinate, if present.
      int hashCode()
      Gets a hashcode for this coordinate.
      static int hashCode​(double x)
      Computes a hash code for a double value, using the algorithm from Joshua Bloch's book Effective Java"
      void setCoordinate​(Coordinate other)
      Sets this Coordinates (x,y,z) values to that of other.
      void setM​(double m)
      Sets the measure value, if supported.
      void setOrdinate​(int ordinateIndex, double value)
      Sets the ordinate for the given index to a given value.
      void setX​(double x)
      Sets the X ordinate value.
      void setY​(double y)
      Sets the Y ordinate value.
      void setZ​(double z)
      Sets the Z ordinate value.
      java.lang.String toString()
      Returns a String of the form (x,y,z) .
      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • NULL_ORDINATE

        public static final double NULL_ORDINATE
        The value used to indicate a null or missing ordinate value. In particular, used for the value of ordinates for dimensions greater than the defined dimension of a coordinate.
        See Also:
        Constant Field Values
      • X

        public static final int X
        Standard ordinate index value for, where X is 0
        See Also:
        Constant Field Values
      • Y

        public static final int Y
        Standard ordinate index value for, where Y is 1
        See Also:
        Constant Field Values
      • Z

        public static final int Z
        Standard ordinate index value for, where Z is 2.

        This constant assumes XYZM coordinate sequence definition, please check this assumption using #getDimension() and #getMeasures() before use.

        See Also:
        Constant Field Values
      • M

        public static final int M
        Standard ordinate index value for, where M is 3.

        This constant assumes XYZM coordinate sequence definition, please check this assumption using #getDimension() and #getMeasures() before use.

        See Also:
        Constant Field Values
      • x

        public double x
        The x-ordinate.
      • y

        public double y
        The y-ordinate.
      • z

        public double z
        The z-ordinate.

        Direct access to this field is discouraged; use getZ().

    • Constructor Detail

      • Coordinate

        public Coordinate​(double x,
                          double y,
                          double z)
        Constructs a Coordinate at (x,y,z).
        Parameters:
        x - the x-ordinate
        y - the y-ordinate
        z - the z-ordinate
      • Coordinate

        public Coordinate()
        Constructs a Coordinate at (0,0,NaN).
      • Coordinate

        public Coordinate​(Coordinate c)
        Constructs a Coordinate having the same (x,y,z) values as other.
        Parameters:
        c - the Coordinate to copy.
      • Coordinate

        public Coordinate​(double x,
                          double y)
        Constructs a Coordinate at (x,y,NaN).
        Parameters:
        x - the x-value
        y - the y-value
    • Method Detail

      • setCoordinate

        public void setCoordinate​(Coordinate other)
        Sets this Coordinates (x,y,z) values to that of other.
        Parameters:
        other - the Coordinate to copy
      • getX

        public double getX()
        Retrieves the value of the X ordinate.
        Returns:
        the value of the X ordinate
      • setX

        public void setX​(double x)
        Sets the X ordinate value.
        Parameters:
        x - the value to set as X
      • getY

        public double getY()
        Retrieves the value of the Y ordinate.
        Returns:
        the value of the Y ordinate
      • setY

        public void setY​(double y)
        Sets the Y ordinate value.
        Parameters:
        y - the value to set as Y
      • getZ

        public double getZ()
        Retrieves the value of the Z ordinate, if present. If no Z value is present returns NaN.
        Returns:
        the value of the Z ordinate, or NaN
      • setZ

        public void setZ​(double z)
        Sets the Z ordinate value.
        Parameters:
        z - the value to set as Z
      • getM

        public double getM()
        Retrieves the value of the measure, if present. If no measure value is present returns NaN.
        Returns:
        the value of the measure, or NaN
      • setM

        public void setM​(double m)
        Sets the measure value, if supported.
        Parameters:
        m - the value to set as M
      • getOrdinate

        public double getOrdinate​(int ordinateIndex)
        Gets the ordinate value for the given index. The base implementation supports values for the index are X, Y, and Z.
        Parameters:
        ordinateIndex - the ordinate index
        Returns:
        the value of the ordinate
        Throws:
        java.lang.IllegalArgumentException - if the index is not valid
      • setOrdinate

        public void setOrdinate​(int ordinateIndex,
                                double value)
        Sets the ordinate for the given index to a given value. The base implementation supported values for the index are X, Y, and Z.
        Parameters:
        ordinateIndex - the ordinate index
        value - the value to set
        Throws:
        java.lang.IllegalArgumentException - if the index is not valid
      • equals2D

        public boolean equals2D​(Coordinate other)
        Returns whether the planar projections of the two Coordinates are equal.
        Parameters:
        other - a Coordinate with which to do the 2D comparison.
        Returns:
        true if the x- and y-coordinates are equal; the z-coordinates do not have to be equal.
      • equals2D

        public boolean equals2D​(Coordinate c,
                                double tolerance)
        Tests if another Coordinate has the same values for the X and Y ordinates, within a specified tolerance value. The Z ordinate is ignored.
        Parameters:
        c - a Coordinate with which to do the 2D comparison.
        tolerance - the tolerance value to use
        Returns:
        true if other is a Coordinate with the same values for X and Y.
      • equals3D

        public boolean equals3D​(Coordinate other)
        Tests if another coordinate has the same values for the X, Y and Z ordinates.
        Parameters:
        other - a Coordinate with which to do the 3D comparison.
        Returns:
        true if other is a Coordinate with the same values for X, Y and Z.
      • equalInZ

        public boolean equalInZ​(Coordinate c,
                                double tolerance)
        Tests if another coordinate has the same value for Z, within a tolerance.
        Parameters:
        c - a coordinate
        tolerance - the tolerance value
        Returns:
        true if the Z ordinates are within the given tolerance
      • equals

        public boolean equals​(java.lang.Object other)
        Returns true if other has the same values for the x and y ordinates. Since Coordinates are 2.5D, this routine ignores the z value when making the comparison.
        Overrides:
        equals in class java.lang.Object
        Parameters:
        other - a Coordinate with which to do the comparison.
        Returns:
        true if other is a Coordinate with the same values for the x and y ordinates.
      • compareTo

        public int compareTo​(Coordinate o)
        Compares this Coordinate with the specified Coordinate for order. This method ignores the z value when making the comparison. Returns:
        • -1 : this.x < other.x || ((this.x == other.x) && (this.y < other.y))
        • 0 : this.x == other.x && this.y = other.y
        • 1 : this.x > other.x || ((this.x == other.x) && (this.y > other.y))
        Note: This method assumes that ordinate values are valid numbers. NaN values are not handled correctly.
        Specified by:
        compareTo in interface java.lang.Comparable<Coordinate>
        Parameters:
        o - the Coordinate with which this Coordinate is being compared
        Returns:
        -1, zero, or 1 as this Coordinate is less than, equal to, or greater than the specified Coordinate
      • toString

        public java.lang.String toString()
        Returns a String of the form (x,y,z) .
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String of the form (x,y,z)
      • clone

        public java.lang.Object clone()
      • copy

        public Coordinate copy()
        Creates a copy of this Coordinate.
        Returns:
        a copy of this coordinate.
      • distance

        public double distance​(Coordinate c)
        Computes the 2-dimensional Euclidean distance to another location. The Z-ordinate is ignored.
        Parameters:
        c - a point
        Returns:
        the 2-dimensional Euclidean distance between the locations
      • distance3D

        public double distance3D​(Coordinate c)
        Computes the 3-dimensional Euclidean distance to another location.
        Parameters:
        c - a coordinate
        Returns:
        the 3-dimensional Euclidean distance between the locations
      • hashCode

        public int hashCode()
        Gets a hashcode for this coordinate.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        a hashcode for this coordinate
      • hashCode

        public static int hashCode​(double x)
        Computes a hash code for a double value, using the algorithm from Joshua Bloch's book Effective Java"
        Parameters:
        x - the value to compute for
        Returns:
        a hashcode for x