Module org.apache.sis.referencing
Package org.apache.sis.geometry

Class GeneralDirectPosition

Object
FormattableObject
AbstractDirectPosition
GeneralDirectPosition
All Implemented Interfaces:
Serializable, Cloneable, Position, Direct­Position
public class GeneralDirectPosition extends AbstractDirectPosition implements Serializable, Cloneable
A mutable Direct­Position (the coordinates of a position) of arbitrary dimension. This particular implementation of Direct­Position 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 Direct­Position2D provides a more efficient implementation.

Coordinate Reference System (CRS) optionality

Since Direct­Positions, as data types, will often be included in larger objects (such as Geometry) that have references to Coordinate­Reference­System, the get­Coordinate­Reference­System() method may returns null if this particular Direct­Position 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 Coordinate­Reference­System.
Since:
0.3
See Also:

  • Field Details

    • coordinates

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

  • Constructor Details

    • GeneralDirectPosition

      public GeneralDirectPosition(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:
      Negative­Array­Size­Exception - 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 notes

      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 General­Direct­Position(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 General­Direct­Position(100.0), not new General­Direct­Position(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(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: 
      POINT(6 10)
      However, this constructor is lenient to other types like POINT ZM.
      Parameters:
      wkt - the POINT or other kind of element to parse.
      Throws:
      Illegal­Argument­Exception - 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:
      get­Dimension in interface Direct­Position
      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 Direct­Position is included in a larger object with such a reference to a CRS.
      Specified by:
      get­Coordinate­Reference­System in interface Direct­Position
      Overrides:
      get­Coordinate­Reference­System in class Abstract­Direct­Position
      Returns:
      the coordinate reference system, or null.

    • setCoordinateReferenceSystem

      public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs) throws MismatchedDimensionException
      Sets the coordinate reference system in which the coordinate is given.
      Parameters:
      crs - the new coordinate reference system, or null.
      Throws:
      Mismatched­Dimension­Exception - 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:
      get­Coordinate in interface Direct­Position
      Overrides:
      get­Coordinate in class Abstract­Direct­Position
      Returns:
      a copy of the coordinates array.

    • setCoordinate

      public void setCoordinate(double... coordinates) throws MismatchedDimensionException
      Sets the coordinate values along all dimensions.
      Parameters:
      coordinates - the new coordinates values, or a null array for setting all coordinate values to Na­N.
      Throws:
      Mismatched­Dimension­Exception - 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:
      get­Ordinate in interface Direct­Position
      Parameters:
      dimension - the dimension in the range 0 to dimension-1.
      Returns:
      the coordinate at the specified dimension.
      Throws:
      Index­Out­Of­Bounds­Exception - 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:
      set­Ordinate in interface Direct­Position
      Overrides:
      set­Ordinate in class Abstract­Direct­Position
      Parameters:
      dimension - the dimension for the coordinate of interest.
      value - the coordinate value of interest.
      Throws:
      Index­Out­Of­Bounds­Exception - if the specified dimension is out of bounds.

    • setLocation

      public void setLocation(DirectPosition position) throws 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:
      set­Location in class Abstract­Direct­Position
      Parameters:
      position - the new position for this point, or null for setting all coordinate values to Na­N.
      Throws:
      Mismatched­Dimension­Exception - 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.: 
      POINT(x₀ x₁ x₂ …)
      This method formats the numbers as with Double​.to­String(double) (i.e. without fixed number of fraction digits). The string returned by this method can be parsed by the General­Direct­Position constructor.
      Overrides:
      to­String in class Abstract­Direct­Position
      Returns:
      this position as a POINT in Well Known Text (WKT) format.

    • 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 Direct­Position​.hash­Code() javadoc. Consequently, it should be possible to mix different Direct­Position implementations in the same hash map.
      Specified by:
      hash­Code in interface Direct­Position
      Overrides:
      hash­Code in class Abstract­Direct­Position
      Returns:
      a hash code value for this position.

    • equals

      public boolean equals(Object object)
      Returns true if the specified object is also a Direct­Position with equal coordinates and equal CRS. This method performs the comparison as documented in the Direct­Position​.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 Direct­Position implementations in the same hash map.
      Specified by:
      equals in interface Direct­Position
      Overrides:
      equals in class Abstract­Direct­Position
      Parameters:
      object - the object to compare with this position.
      Returns:
      true if the given object is equal to this position.