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 `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 needed 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
See Also:
  - `GridCoverage​.Evaluator​.toGridCoordinates(DirectPosition)`
  - Serialized Form

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FractionalGridCoordinates(int dimension)`
  Creates a new grid coordinates with the given number of dimensions.
  `FractionalGridCoordinates(FractionalGridCoordinates other)`
  Creates a new grid coordinates initialized to a copy of the given coordinates.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object object)`
  Compares this grid coordinates with the specified object for equality.
  `double`
  `getCoordinateFractional(int dimension)`
  Returns a grid coordinate value together with its fractional part, if any.
  `long`
  `getCoordinateValue(int dimension)`
  Returns the grid coordinate value at the specified dimension.
  `long[]`
  `getCoordinateValues()`
  Returns one integer value for each dimension of the grid.
  `int`
  `getDimension()`
  Returns the number of dimension of this grid coordinates.
  `int`
  `hashCode()`
  Returns a hash code value for this grid coordinates.
  `void`
  `setCoordinateValue(int dimension, long value)`
  Sets the coordinate value at the specified dimension.
  `GridExtent`
  `toExtent(GridExtent bounds, long... size)`
  Creates a new grid extent around this grid coordinates.
  `DirectPosition`
  `toPosition(MathTransform gridToCRS)`
  Returns the grid coordinates converted to a geospatial position using the given transform.
  `String`
  `toString()`
  Returns a string representation of this grid coordinates for debugging purpose.

  ### Methods inherited from class Object

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### FractionalGridCoordinates

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

    #### Usage 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:
       - `extent.getLow(i)` ≤ `getCoordinateFractional(i)`
       - `extent.getHigh(i)` ≥ `getCoordinateFractional(i)`
    2. If `bounds​.getSize(i)` ≥ `size[i]` and `size[i]` ≠ 0 then:
       - `extent.getSize(i)` = `size[i]`

    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 [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:
      `IllegalArgumentException` - if a `size` value is negative.
      `ArithmeticException` - if a coordinate value is outside the range of `long` values.
      `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.

  - ### toPosition

    public DirectPosition toPosition(MathTransform gridToCRS) throws 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:
      `TransformException` - if the grid coordinates cannot be converted by `gridToCRS`.
    See Also:
      - `GridCoverage​.Evaluator​.toGridCoordinates(DirectPosition)`

  - ### toString

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

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