Class FractionalGridCoordinates

java.lang.Object
org.apache.sis.coverage.grid.FractionalGridCoordinates
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
FractionalGridCoordinates.Position

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 GridCoverage. They are normally integer numbers, but fractional parts may exist for example after converting a geospatial DirectPosition to grid coordinates. Preserving that fractional part is sometimes useful, e.g. for interpolations. This class can store such fractional part and can also compute a GridExtent 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 ArithmeticException is thrown.

Since:
1.1
Version:
1.2
See Also:
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • coordinates

      final double[] coordinates
      The grid coordinates as floating-point numbers.
  • Constructor Details

    • FractionalGridCoordinates

      public FractionalGridCoordinates(int dimension)
      Creates a new grid coordinates with the given number of dimensions.
      Note: FractionalGridCoordinates 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 getCoordinateValue(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 GridCoordinates object.
      Throws:
      ArithmeticException - 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 ArithmeticException 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:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      ArithmeticException - 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:
      IndexOutOfBoundsException - 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:
      IndexOutOfBoundsException - if the given index is negative or is equal or greater than the grid dimension.
      ArithmeticException - 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.getSize(i) ≥ 2 and no shift (see below) then:
      2. If bounds.getSize(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 PointOutsideCoverageException 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 [lowhigh+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:
      IllegalArgumentException - if a size value is negative.
      ArithmeticException - if a coordinate value is outside the range of long values.
      org.opengis.geometry.MismatchedDimensionException - if bounds dimension is not equal to grid coordinates dimension.
      PointOutsideCoverageException - if the grid coordinates (rounded to nearest integers) are outside the given bounds.
    • toExtent

      final GridExtent toExtent(GridExtent bounds, long[] size, boolean nullIfOutside)
      Implementation of toExtent(GridExtent, long...) with the option to replace PointOutsideCoverageException by null return value.
      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 for automatic sizes (1 or 2).
      nullIfOutside - whether to return null instead of throwing an exception if given point is outside coverage bounds.
      Returns:
      a grid extent containing grid coordinates, or null if outside and nullIfOutside is true.
    • toPosition

      public org.opengis.geometry.DirectPosition toPosition(org.opengis.referencing.operation.MathTransform gridToCRS) throws org.opengis.referencing.operation.TransformException
      Returns the grid coordinates converted to a geospatial position using the given transform. The gridToCRS argument is typically GridGeometry.getGridToCRS(PixelInCell) with PixelInCell.CELL_CENTER.
      Parameters:
      gridToCRS - the transform to apply on grid coordinates.
      Returns:
      the grid coordinates converted using the given transform.
      Throws:
      org.opengis.referencing.operation.TransformException - if the grid coordinates cannot be converted by gridToCRS.
      See Also:
    • pointOutsideCoverage

      final String pointOutsideCoverage(GridExtent bounds)
      Creates an error message for a grid coordinates out of bounds. This method tries to detect the dimension of the out-of-bounds coordinate by searching for the dimension with largest error.
      Parameters:
      bounds - the expected bounds, or null if unknown.
      Returns:
      message to provide to PointOutsideCoverageException, or null if the given bounds were null.
    • toString

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

      private void writeCoordinates(StringBuilder buffer)
      Writes coordinates in the given buffer.
    • hashCode

      public int hashCode()
      Returns a hash code value for this grid coordinates.
      Overrides:
      hashCode 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.