Module org.apache.sis.feature
Package org.apache.sis.coverage.grid

Class FractionalGridCoordinates

Object
FractionalGridCoordinates
All Implemented Interfaces:
Serializable
public class FractionalGridCoordinates extends Object implements Serializable
Grid coordinates which may have fraction digits after the integer part. Grid coordinates specify the location of a cell within a Grid­Coverage. They are normally integer numbers, but fractional parts may exist for example after converting a geospatial Direct­Position to grid coordinates. Preserving that fractional part is needed for interpolations. This class can store such fractional part and can also compute a Grid­Extent containing the coordinates, which can be used for requesting data for interpolations.

Current implementation stores coordinate values as double precision floating-point numbers and rounds them to 64-bits integers on the fly. If a double cannot be returned as a long, or if a long cannot be stored as a double, then an Arithmetic­Exception is thrown.

Since:
1.1
See Also:

  • Constructor Details

    • FractionalGridCoordinates

      public FractionalGridCoordinates(int dimension)
      Creates a new grid coordinates with the given number of dimensions.

      Usage note

      Fractional­Grid­Coordinates are usually not created directly, but are instead obtained indirectly for example from the conversion of a geospatial position.
      Parameters:
      dimension - the number of dimensions.

    • FractionalGridCoordinates

      public FractionalGridCoordinates(FractionalGridCoordinates other)
      Creates a new grid coordinates initialized to a copy of the given coordinates.
      Parameters:
      other - the coordinates to copy.

  • Method Details

    • getDimension

      public int getDimension()
      Returns the number of dimension of this grid coordinates.
      Returns:
      the number of dimensions.

    • getCoordinateValues

      public long[] getCoordinateValues()
      Returns one integer value for each dimension of the grid. The default implementation invokes get­Coordinate­Value(int) for each element in the returned array.
      Returns:
      a copy of the coordinates. Changes in the returned array will not be reflected back in this Grid­Coordinates object.
      Throws:
      Arithmetic­Exception - if a coordinate value is outside the range of values representable as a 64-bits integer value.

    • getCoordinateValue

      public long getCoordinateValue(int dimension)
      Returns the grid coordinate value at the specified dimension. Floating-point values are rounded to the nearest 64-bits integer values. If the coordinate value is NaN or outside the range of long values, then an Arithmetic­Exception is thrown.
      Parameters:
      dimension - the dimension for which to obtain the coordinate value.
      Returns:
      the coordinate value at the given dimension, rounded to nearest integer.
      Throws:
      Index­Out­Of­Bounds­Exception - if the given index is negative or is equal or greater than the grid dimension.
      Arithmetic­Exception - if the coordinate value is outside the range of values representable as a 64-bits integer value.

    • getCoordinateFractional

      public double getCoordinateFractional(int dimension)
      Returns a grid coordinate value together with its fractional part, if any.
      Parameters:
      dimension - the dimension for which to obtain the coordinate value.
      Returns:
      the coordinate value at the given dimension.
      Throws:
      Index­Out­Of­Bounds­Exception - if the given index is negative or is equal or greater than the grid dimension.

    • setCoordinateValue

      public void setCoordinateValue(int dimension, long value)
      Sets the coordinate value at the specified dimension. The given value shall be convertible to double without precision lost.
      Parameters:
      dimension - the dimension for which to set the coordinate value.
      value - the new value.
      Throws:
      Index­Out­Of­Bounds­Exception - if the given index is negative or is equal or greater than the grid dimension.
      Arithmetic­Exception - if this method cannot store the given grid coordinate without precision lost.

    • toExtent

      public GridExtent toExtent(GridExtent bounds, long... size)
      Creates a new grid extent around this grid coordinates. The returned extent will have the same number of dimensions than this grid coordinates. For each dimension i the following relationships will hold:
      1. If extent.get­Size(i) ≥ 2 and no shift (see below) then:
      2. If bounds​.get­Size(i) ≥ size[i] and size[i] ≠ 0 then:

      The size argument is optional and can be incomplete (i.e. the number of size values can be less than the number of dimensions). For each dimension i, if a size[i] value is provided and is not zero, then this method tries to expand the extent in that dimension to the specified size[i] value as shown in constraint #2 above. Otherwise the default size is the smallest possible extent that met constraint #1 above, clipped to the bounds. This implies a size of 1 if the grid coordinate in that dimension is an integer, or a size of 2 (before clipping to the bounds) if the grid coordinate has a fractional part.

      The bounds argument is also optional. If non-null, then this method enforces the following additional rules:

      • Coordinates rounded to nearest integers must be inside the given bounds, otherwise a Point­Outside­Coverage­Exception is thrown.
      • If the computed extent overlaps an area outside the bounds, then the extent will be shifted (if an explicit size was given) or clipped (if automatic size is used) in order to be be fully contained inside the bounds.
      • If a given size is larger than the corresponding bounds size, then the returned extent will be clipped to the bounds.

      In all cases, this method tries to keep the grid coordinates close to the center of the returned extent. A shift may exist if necessary for keeping the extent inside the bounds argument, but will never move the grid coordinates outside the [low … high+1) range of returned extent.

      Parameters:
      bounds - if the coordinates shall be contained inside a grid, that grid extent. Otherwise null.
      size - the desired extent sizes as strictly positive numbers, or 0 sentinel values for automatic sizes (1 or 2 depending on bounds and coordinate values). This array may have any length; if shorter than the number of dimensions, missing values default to 0. If longer than the number of dimensions, extra values are ignored.
      Returns:
      a grid extent of the given size (if possible) containing those grid coordinates.
      Throws:
      Illegal­Argument­Exception - if a size value is negative.
      Arithmetic­Exception - if a coordinate value is outside the range of long values.
      Mismatched­Dimension­Exception - if bounds dimension is not equal to grid coordinates dimension.
      Point­Outside­Coverage­Exception - if the grid coordinates (rounded to nearest integers) are outside the given bounds.

    • toPosition

      public DirectPosition toPosition(MathTransform gridToCRS) throws TransformException
      Returns the grid coordinates converted to a geospatial position using the given transform. The grid­To­CRS argument is typically Grid­Geometry​.get­Grid­To­CRS(Pixel­In­Cell) with Pixel­In­Cell​.CELL_CENTER.
      Parameters:
      grid­To­CRS - the transform to apply on grid coordinates.
      Returns:
      the grid coordinates converted using the given transform.
      Throws:
      Transform­Exception - if the grid coordinates cannot be converted by grid­To­CRS.
      See Also:

    • toString

      public String toString()
      Returns a string representation of this grid coordinates for debugging purpose.
      Overrides:
      to­String in class Object

    • hashCode

      public int hashCode()
      Returns a hash code value for this grid coordinates.
      Overrides:
      hash­Code in class Object

    • equals

      public boolean equals(Object object)
      Compares this grid coordinates with the specified object for equality.
      Overrides:
      equals in class Object
      Parameters:
      object - the object to compares with this grid coordinates.
      Returns:
      true if the given object is equal to this grid coordinates.