Class Coordinate

java.lang.Object
org.locationtech.jts.geom.Coordinate
All Implemented Interfaces:
Serializable, Cloneable, Comparable<Coordinate>
Direct Known Subclasses:
CoordinateXY, CoordinateXYM, CoordinateXYZM, ExtendedCoordinate
public class Coordinate extends Object implements Comparable<Coordinate>, Cloneable, 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:

  • 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 final int
    M
    Standard ordinate index value for, where M is 3.
    static final double
    NULL_ORDINATE
    The value used to indicate a null or missing ordinate value.
    double
    x
    The x-ordinate.
    static final int
    X
    Standard ordinate index value for, where X is 0
    double
    y
    The y-ordinate.
    static final int
    Y
    Standard ordinate index value for, where Y is 1
    double
    z
    The z-ordinate.
    static final 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

    Modifier and Type
    Method
    Description
    Object
    clone()
     
    int
    compareTo(Coordinate o)
    Compares this Coordinate with the specified Coordinate for order.
    Coordinate
    copy()
    Creates a copy of this Coordinate.
    Coordinate
    create()
    Create a new Coordinate of the same type as this Coordinate, but with no values.
    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(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"
    boolean
    isValid()
    Tests if the coordinate has valid X and Y ordinate values.
    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.
    String
    toString()
    Returns a String of the form (x,y,z) .

    Methods inherited from class Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • 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:

    • X

      public static final int X
      Standard ordinate index value for, where X is 0
      See Also:

    • Y

      public static final int Y
      Standard ordinate index value for, where Y is 1
      See Also:

    • 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 CoordinateSequence.getDimension() and CoordinateSequence.getMeasures() before use.

      See Also:

    • 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 CoordinateSequence.getDimension() and CoordinateSequence.getMeasures() before use.

      See Also:

    • 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 Details

    • 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 Details

    • 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:
      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:
      IllegalArgumentException - if the index is not valid

    • isValid

      public boolean isValid()
      Tests if the coordinate has valid X and Y ordinate values. An ordinate value is valid iff it is finite.
      Returns:
      true if the coordinate is valid
      See Also:

    • 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(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 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 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 String toString()
      Returns a String of the form (x,y,z) .
      Overrides:
      toString in class Object
      Returns:
      a String of the form (x,y,z)

    • clone

      public Object clone()
      Overrides:
      clone in class Object

    • copy

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

    • create

      public Coordinate create()
      Create a new Coordinate of the same type as this Coordinate, but with no values.
      Returns:
      a new 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 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