Package org.apache.sis.geometry

## Class DirectPosition2D

- Object
- - Point2D
  - - Point2D.Double
    - - DirectPosition2D

- All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Position`, `DirectPosition`

      public class DirectPosition2D
      extends Point2D.Double
      implements DirectPosition, Cloneable

  A two-dimensional position on top of Java2D point. This implementation is provided for inter-operability between Java2D and GeoAPI.

  This class inherits x and y fields. But despite their names, they don't need to be oriented toward East and North respectively. The (x,y) axis can have any direction and should be understood as coordinate 0 and coordinate 1 values instead. This is not specific to this implementation; in Java2D too, the visual axis orientation depend on the affine transform in the graphics context.

  Note: The rational for avoiding axis orientation restriction is that other `DirectPosition` implementations do not have such restriction, and it would be hard to generalize. For example there is no clear "x" or "y" classification for North-East direction.
  Caution when used in collections
  Do not mix instances of this class with ordinary `Point2D` instances in a `HashSet` or as `HashMap` keys. It is not possible to met both `Point2D​.hashCode()` and `DirectPosition​.hashCode()` contracts, and this class chooses to implements the later. Consequently, the `hashCode()` method of this class is inconsistent with `Point2D​.equals(Object)` but is consistent with `DirectPosition​.equals(Object)`.

  In other words, it is safe to add instances of `DirectPosition2D` in a `HashSet<DirectPosition>`, but it is unsafe to add them in a `HashSet<Point2D>`. Collections that do not rely on hash codes, like `ArrayList`, are safe in all cases.

  Since:
    0.3
  See Also:
    `DirectPosition1D`, `GeneralDirectPosition`, `Point2D`, `CoordinateFormat`, Serialized Form

  Defined in the `sis-referencing` module

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class Point2D

      `Point2D​.Double, Point2D​.Float`

  - ### Field Summary

    - ### Fields inherited from class Point2D.Double

      `x, y`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DirectPosition2D()` | Constructs a position initialized to (0,0) with a `null` coordinate reference system.
    `DirectPosition2D​(double x, double y)` | Constructs a 2D position from the specified coordinates.
    `DirectPosition2D​(CharSequence wkt)` | Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format.
    `DirectPosition2D​(DirectPosition position)` | Constructs a position initialized to the same values than the specified point.
    `DirectPosition2D​(CoordinateReferenceSystem crs)` | Constructs a position initialized to (0,0) with the specified coordinate reference system.
    `DirectPosition2D​(CoordinateReferenceSystem crs, double x, double y)` | Constructs a 2D position from the specified coordinates in the specified CRS.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DirectPosition2D` | `clone()` | Returns a clone of this point.
    `boolean` | `equals​(Object object)` | Compares this point with the specified object for equality.
    `double[]` | `getCoordinate()` | Returns a sequence of numbers that hold the coordinate of this position in its reference system.
    `CoordinateReferenceSystem` | `getCoordinateReferenceSystem()` | Returns the coordinate reference system in which the coordinate is given.
    `int` | `getDimension()` | The length of coordinate sequence (the number of entries).
    `DirectPosition` | `getDirectPosition()` | Returns always `this`, the direct position for this position.
    `double` | `getOrdinate​(int dimension)` | Returns the coordinate at the specified dimension.
    `int` | `hashCode()` | Returns a hash value for this coordinate.
    `void` | `setCoordinateReferenceSystem​(CoordinateReferenceSystem crs)` | Sets the coordinate reference system in which the coordinate is given.
    `void` | `setLocation​(Point2D position)` | Sets this coordinate to the specified point.
    `void` | `setOrdinate​(int dimension, double value)` | Sets the coordinate value along the specified dimension.
    `String` | `toString()` | Formats this position in the Well Known Text (WKT) format.

    - ### Methods inherited from class Point2D.Double

      `getX, getY, setLocation`

    - ### Methods inherited from class Point2D

      `distance, distance, distance, distanceSq, distanceSq, distanceSq`

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### DirectPosition2D

          public DirectPosition2D()

      Constructs a position initialized to (0,0) with a `null` coordinate reference system.

    - #### DirectPosition2D

          public DirectPosition2D​(CoordinateReferenceSystem crs)

      Constructs a position initialized to (0,0) with the specified coordinate reference system.
      Parameters:
        `crs` - the coordinate reference system, or `null`.

    - #### DirectPosition2D

          public DirectPosition2D​(double x,
                                  double y)

      Constructs a 2D position from the specified coordinates. Despite their names, the (x,y) coordinates don't need to be oriented toward (East, North). Those parameter names simply match the x and y fields. See the class javadoc for details.
      Parameters:
        `x` - the first coordinate value (not necessarily horizontal).
        `y` - the second coordinate value (not necessarily vertical).

    - #### DirectPosition2D

          public DirectPosition2D​(CoordinateReferenceSystem crs,
                                  double x,
                                  double y)

      Constructs a 2D position from the specified coordinates in the specified CRS. Despite their names, the (x,y) coordinates don't need to be oriented toward (East, North). Those parameter names simply match the x and y fields. The actual axis orientations are determined by the specified CRS. See the class javadoc for details.
      Parameters:
        `crs` - the coordinate reference system, or `null`.
        `x` - the first coordinate value (not necessarily horizontal).
        `y` - the second coordinate value (not necessarily vertical).

    - #### DirectPosition2D

          public DirectPosition2D​(DirectPosition position)
                           throws MismatchedDimensionException

      Constructs a position initialized to the same values than the specified point.
      Parameters:
        `position` - the position to copy.
      Throws:
        `MismatchedDimensionException` - if the given position is not two-dimensional.
      See Also:
        `setLocation(Point2D)`

    - #### DirectPosition2D

          public DirectPosition2D​(CharSequence wkt)
                           throws IllegalArgumentException

      Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format. The given string is typically a `POINT` element like below:

      >     POINT(6 10)

      Parameters:
        `wkt` - the `POINT` or other kind of element to parse.
      Throws:
        `IllegalArgumentException` - if the given string can not be parsed.
        `MismatchedDimensionException` - if the given point is not two-dimensional.
      See Also:
        `toString()`, `CoordinateFormat`

  - ### Method Detail

    - #### getDirectPosition

          public final DirectPosition getDirectPosition()

      Returns always `this`, the direct position for this position.
      Specified by:
        `getDirectPosition` in interface `Position`

    - #### getDimension

          public final int getDimension()

      The length of coordinate sequence (the number of entries). This is always 2 for `DirectPosition2D` objects.
      Specified by:
        `getDimension` in interface `DirectPosition`
      Returns:
        the dimensionality of this position.

    - #### getCoordinateReferenceSystem

          public final CoordinateReferenceSystem getCoordinateReferenceSystem()

      Returns the coordinate reference system in which the coordinate is given. May be `null` if this particular `DirectPosition` is included in a larger object with such a reference to a CRS.
      Specified by:
        `getCoordinateReferenceSystem` in interface `DirectPosition`
      Returns:
        the coordinate reference system, or `null`.

    - #### setCoordinateReferenceSystem

          public void setCoordinateReferenceSystem​(CoordinateReferenceSystem crs)

      Sets the coordinate reference system in which the coordinate is given.
      Parameters:
        `crs` - the new coordinate reference system, or `null`.

    - #### getCoordinate

          public final double[] getCoordinate()

      Returns a sequence of numbers that hold the coordinate of this position in its reference system.
      API note: This method is final for ensuring consistency with the `x` and `y` fields, which are public.
      Specified by:
        `getCoordinate` in interface `DirectPosition`
      Returns:
        the coordinate.

    - #### getOrdinate

          public final double getOrdinate​(int dimension)
                                   throws IndexOutOfBoundsException

      Returns the coordinate at the specified dimension.
      API note: This method is final for ensuring consistency with the `x` and `y` fields, which are public.
      Specified by:
        `getOrdinate` in interface `DirectPosition`
      Parameters:
        `dimension` - the dimension in the range 0 to 1 inclusive.
      Returns:
        the coordinate at the specified dimension.
      Throws:
        `IndexOutOfBoundsException` - if the specified dimension is out of bounds.

    - #### setOrdinate

          public void setOrdinate​(int dimension,
                                  double value)
                           throws IndexOutOfBoundsException

      Sets the coordinate value along the specified dimension.
      Specified by:
        `setOrdinate` in interface `DirectPosition`
      Parameters:
        `dimension` - the dimension for the coordinate of interest.
        `value` - the coordinate value of interest.
      Throws:
        `IndexOutOfBoundsException` - if the specified dimension is out of bounds.

    - #### setLocation

          public void setLocation​(Point2D position)

      Sets this coordinate to the specified point. If the specified position is also a `DirectPosition` containing a non-null coordinate reference system (CRS), then the CRS for this position will be set to the CRS of the given point.
      Overrides:
        `setLocation` in class `Point2D`
      Parameters:
        `position` - the new position for this point.

    - #### toString

          public String toString()

      Formats this position in the Well Known Text (WKT) format. The output is like below:

      >     POINT(x y)

      The string returned by this method can be parsed by the `DirectPosition2D` constructor.
      Overrides:
        `toString` in class `Point2D​.Double`

    - #### hashCode

          public int hashCode()

      Returns a hash value for this coordinate. This method implements the `DirectPosition​.hashCode()` contract, not the `Point2D​.hashCode()` contract.
      Specified by:
        `hashCode` in interface `DirectPosition`
      Overrides:
        `hashCode` in class `Point2D`
      Returns:
        a hash code value for this position.

    - #### equals

          public boolean equals​(Object object)

      Compares this point with the specified object for equality. If the given object implements the `DirectPosition` interface, then the comparison is performed as specified in the `DirectPosition​.equals(Object)` contract. Otherwise the comparison is performed as specified in the `Point2D​.equals(Object)` contract.
      Specified by:
        `equals` in interface `DirectPosition`
      Overrides:
        `equals` in class `Point2D`
      Parameters:
        `object` - the object to compare with this position.
      Returns:
        `true` if the given object is equal to this position.

    - #### clone

          public DirectPosition2D clone()

      Returns a clone of this point.
      Overrides:
        `clone` in class `Point2D`
      Returns:
        a clone of this position.