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

  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.
  `final double[]`
  `getCoordinate()`
  Returns a sequence of numbers that hold the coordinate of this position in its reference system.
  `final CoordinateReferenceSystem`
  `getCoordinateReferenceSystem()`
  Returns the coordinate reference system in which the coordinate is given.
  `final int`
  `getDimension()`
  The length of coordinate sequence (the number of entries).
  `final DirectPosition`
  `getDirectPosition()`
  Returns always `this`, the direct position for this position.
  `final 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 Details

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

  - ### 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.