Class GeneralDirectPosition

All Implemented Interfaces:
Serializable, Cloneable, org.opengis.geometry.coordinate.Position, org.opengis.geometry.DirectPosition
Direct Known Subclasses:
PositionTransformer

public class GeneralDirectPosition extends AbstractDirectPosition implements Serializable, Cloneable
A mutable DirectPosition (the coordinates of a position) of arbitrary dimension. This particular implementation of DirectPosition is said "General" because it uses an array of coordinates of an arbitrary length. If the direct position is known to be always two-dimensional, then DirectPosition2D provides a more efficient implementation.

Coordinate Reference System (CRS) optionality

Since DirectPositions, as data types, will often be included in larger objects (such as Geometry) that have references to CoordinateReferenceSystem, the getCoordinateReferenceSystem() method may returns null if this particular DirectPosition is included in such larger object. In this case, the coordinate reference system is implicitly assumed to take on the value of the containing object's CoordinateReferenceSystem.
Since:
0.3
Version:
1.2
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    final double[]
    The coordinates of the direct position.
    private static Field
    Used for setting the coordinates field during a clone() operation only.
    private org.opengis.referencing.crs.CoordinateReferenceSystem
    The coordinate reference system for this position, or null.
    private static final long
    Serial number for inter-operability with different versions.
  • Constructor Summary

    Constructors
    Constructor
    Description
    GeneralDirectPosition(double... coordinates)
    Constructs a position with the specified coordinates.
    GeneralDirectPosition(int dimension)
    Constructs a position with the specified number of dimensions.
    Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format.
    GeneralDirectPosition(org.opengis.geometry.DirectPosition point)
    Constructs a position initialized to the same values than the specified point.
    GeneralDirectPosition(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Constructs a position using the specified coordinate reference system.
  • Method Summary

    Modifier and Type
    Method
    Description
    Returns a deep copy of this position.
    boolean
    equals(Object object)
    Returns true if the specified object is also a DirectPosition with equal coordinates and equal CRS.
    final double[]
    Returns a sequence of numbers that hold the coordinate of this position in its reference system.
    final org.opengis.referencing.crs.CoordinateReferenceSystem
    Returns the coordinate reference system in which the coordinate is given.
    (package private) static Field
    Returns the "coordinates" field of the given class and gives write permission to it.
    final int
    The length of coordinate sequence (the number of entries).
    final double
    getOrdinate(int dimension)
    Returns the coordinate at the specified dimension.
    int
    Returns a hash value for this coordinate tuple.
    void
    setCoordinate(double... coordinates)
    Sets the coordinate values along all dimensions.
    void
    setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
    Sets the coordinate reference system in which the coordinate is given.
    void
    setLocation(org.opengis.geometry.DirectPosition position)
    Sets this coordinate to the specified direct position.
    void
    setOrdinate(int dimension, double value)
    Sets the coordinate value along the specified dimension.
    Formats this position in the Well Known Text (WKT) format.

    Methods inherited from class org.apache.sis.geometry.AbstractDirectPosition

    castOrCopy, formatTo, getDirectPosition, normalize, parse, toString

    Methods inherited from class org.apache.sis.io.wkt.FormattableObject

    print, toString, toWKT

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      Serial number for inter-operability with different versions.
      See Also:
    • coordinatesField

      private static volatile Field coordinatesField
      Used for setting the coordinates field during a clone() operation only. Will be fetch when first needed.
    • coordinates

      public final double[] coordinates
      The coordinates of the direct position. The length of this array is the dimension of this direct position.
    • crs

      private org.opengis.referencing.crs.CoordinateReferenceSystem crs
      The coordinate reference system for this position, or null.
  • Constructor Details

    • GeneralDirectPosition

      public GeneralDirectPosition(org.opengis.referencing.crs.CoordinateReferenceSystem crs)
      Constructs a position using the specified coordinate reference system. The number of dimensions is inferred from the coordinate reference system. All coordinate values are initialized to zero.
      Parameters:
      crs - the coordinate reference system to be given to this position.
    • GeneralDirectPosition

      public GeneralDirectPosition(int dimension) throws NegativeArraySizeException
      Constructs a position with the specified number of dimensions. All coordinate values are initialized to zero.
      Parameters:
      dimension - number of dimensions.
      Throws:
      NegativeArraySizeException - if dimension is negative.
    • GeneralDirectPosition

      public GeneralDirectPosition(double... coordinates)
      Constructs a position with the specified coordinates. This constructor assigns the given array directly (without clone) to the coordinates field. Consequently, callers shall not recycle the same array for creating many instances.
      Implementation note: the array is not cloned because this is usually not needed, especially in the context of variable argument lengths since the array is often created implicitly. Furthermore, the coordinates field is public, so cloning the array would not protect the state of this object anyway.

      Caution: if only one number is specified, make sure that the number type is double, float or long otherwise the GeneralDirectPosition(int) constructor would be invoked with a very different meaning. For example, for creating a one-dimensional coordinate initialized to the coordinate value 100, use new GeneralDirectPosition(100.0), not new GeneralDirectPosition(100), because the latter would actually create a position with 100 dimensions.

      Parameters:
      coordinates - the coordinate values. This array is not cloned.
    • GeneralDirectPosition

      public GeneralDirectPosition(org.opengis.geometry.DirectPosition point)
      Constructs a position initialized to the same values than the specified point. This is a copy constructor.
      Parameters:
      point - the position to copy.
    • GeneralDirectPosition

      public GeneralDirectPosition(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: However, this constructor is lenient to other types like POINT ZM.
      Parameters:
      wkt - the POINT or other kind of element to parse.
      Throws:
      IllegalArgumentException - if the given string cannot be parsed.
      See Also:
  • Method Details

    • getDimension

      public final int getDimension()
      The length of coordinate sequence (the number of entries). This is always equals to the length of the coordinates array.
      Specified by:
      getDimension in interface org.opengis.geometry.DirectPosition
      Returns:
      the dimensionality of this position.
    • getCoordinateReferenceSystem

      public final org.opengis.referencing.crs.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 org.opengis.geometry.DirectPosition
      Overrides:
      getCoordinateReferenceSystem in class AbstractDirectPosition
      Returns:
      the coordinate reference system, or null.
    • setCoordinateReferenceSystem

      public void setCoordinateReferenceSystem(org.opengis.referencing.crs.CoordinateReferenceSystem crs) throws org.opengis.geometry.MismatchedDimensionException
      Sets the coordinate reference system in which the coordinate is given.
      Parameters:
      crs - the new coordinate reference system, or null.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the specified CRS does not have the expected number of dimensions.
    • 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 coordinates, array field, which is public.
      Specified by:
      getCoordinate in interface org.opengis.geometry.DirectPosition
      Overrides:
      getCoordinate in class AbstractDirectPosition
      Returns:
      a copy of the coordinates array.
    • setCoordinate

      public void setCoordinate(double... coordinates) throws org.opengis.geometry.MismatchedDimensionException
      Sets the coordinate values along all dimensions.
      Parameters:
      coordinates - the new coordinates values, or a null array for setting all coordinate values to NaN.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the length of the specified array is not equals to the dimension of this position.
    • 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 coordinates, array field, which is public.
      Specified by:
      getOrdinate in interface org.opengis.geometry.DirectPosition
      Parameters:
      dimension - the dimension in the range 0 to dimension-1.
      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 org.opengis.geometry.DirectPosition
      Overrides:
      setOrdinate in class AbstractDirectPosition
      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(org.opengis.geometry.DirectPosition position) throws org.opengis.geometry.MismatchedDimensionException
      Sets this coordinate to the specified direct position. If the specified position contains a coordinate reference system (CRS), then the CRS for this position will be set to the CRS of the specified position.
      Overrides:
      setLocation in class AbstractDirectPosition
      Parameters:
      position - the new position for this point, or null for setting all coordinate values to NaN.
      Throws:
      org.opengis.geometry.MismatchedDimensionException - if the given position does not have the expected dimension.
    • toString

      public String toString()
      Formats this position in the Well Known Text (WKT) format. The returned string is like below, where x₀, x₁, x₂, etc. are the coordinate values at index 0, 1, 2, etc.: This method formats the numbers as with Double.toString(double) (i.e. without fixed number of fraction digits). The string returned by this method can be parsed by the GeneralDirectPosition constructor.
      Overrides:
      toString in class AbstractDirectPosition
      Returns:
      this position as a POINT in Well Known Text (WKT) format.
    • getCoordinatesField

      static Field getCoordinatesField(Class<?> type) throws NoSuchFieldException
      Returns the "coordinates" field of the given class and gives write permission to it. This method should be invoked only from clone() method.
      Throws:
      NoSuchFieldException
    • clone

      public GeneralDirectPosition clone()
      Returns a deep copy of this position.
      Overrides:
      clone in class Object
      Returns:
      a copy of this direct position.
    • hashCode

      public int hashCode()
      Returns a hash value for this coordinate tuple. This method returns a value compliant with the contract documented in the DirectPosition.hashCode() javadoc. Consequently, it should be possible to mix different DirectPosition implementations in the same hash map.
      Specified by:
      hashCode in interface org.opengis.geometry.DirectPosition
      Overrides:
      hashCode in class AbstractDirectPosition
      Returns:
      a hash code value for this position.
    • equals

      public boolean equals(Object object)
      Returns true if the specified object is also a DirectPosition with equal coordinates and equal CRS. This method performs the comparison as documented in the DirectPosition.equals(Object) javadoc. In particular, the given object is not required to be of the same implementation class. Consequently, it should be possible to mix different DirectPosition implementations in the same hash map.
      Specified by:
      equals in interface org.opengis.geometry.DirectPosition
      Overrides:
      equals in class AbstractDirectPosition
      Parameters:
      object - the object to compare with this position.
      Returns:
      true if the given object is equal to this position.