# Class GridGeometry

Object
GridGeometry

All Implemented Interfaces:
  `Serializable`, `LenientComparable`

public class GridGeometry extends Object implements LenientComparable, Serializable
Valid extent of grid coordinates together with the transform from those grid coordinates to real world coordinates. `GridGeometry` contains:

- A grid extent (a.k.a. grid envelope), often inferred from the `RenderedImage` size.
- A grid to CRS transform, which may be inferred from the grid extent and the georeferenced envelope.
- A georeferenced envelope, which can be inferred from the grid extent and the grid to CRS transform.
- An optional Coordinate Reference System (CRS) specified as part of the georeferenced envelope. This CRS is the target of the grid to CRS transform.
- An estimation of `grid resolution` along each CRS axes, computed from the grid to CRS transform and eventually from the grid extent.
- An indication of whether conversion for some axes is linear or not.

The first three properties should be mandatory, but are allowed to be temporarily absent during grid coverage construction. Temporarily absent properties are allowed because they may be inferred from a wider context. For example, a `GridGeometry` knows nothing about `RenderedImage`, but `GridCoverage2D` has this information and may use it for providing a missing grid extent. By default, any request for an undefined property will throw an `IncompleteGridGeometryException`. In order to check if a property is defined, use `isDefined(int)`.

## Non-linear referencing

A key property is the "grid to CRS" conversion, which defines how to map pixel coordinates to "real world" coordinates such as latitudes and longitudes. This relationship is often linear (an affine transform), but not necessarily; `GridGeometry` accepts non-linear conversions as well. Non-linear conversions may occur with images using localization grids, but non-linear conversions should not be used for expressing map projections (projections should be specified in the Coordinate Reference System (CRS) instead).

Some applications cannot handle non-linear "grid to CRS" conversions. For example, encoding an image in a GeoTIFF file is much simpler if the "grid to CRS" conversion is linear. The `DomainLinearizer` class can be used for replacing non-linear conversions by linear approximations.

## Multi-threading

`GridGeometry` instances are immutable and thread-safe. The same instance can be shared by different `GridCoverage` instances.

Since:
  1.0
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `CRS`
  A bitmask to specify the validity of the Coordinate Reference System property.
  `protected final ImmutableEnvelope`
  `envelope`
  The geodetic envelope, or `null` if unknown.
  `static final int`
  `ENVELOPE`
  A bitmask to specify the validity of the geodetic envelope property.
  `protected final GridExtent`
  `extent`
  The valid domain of a grid coverage, or `null` if unknown.
  `static final int`
  `EXTENT`
  A bitmask to specify the validity of the grid extent property.
  `static final int`
  `GEOGRAPHIC_EXTENT`
  A bitmask to specify the validity of the geographic bounding box.
  `static final int`
  `GRID_TO_CRS`
  A bitmask to specify the validity of the grid to CRS transform.
  `protected final MathTransform`
  `gridToCRS`
  The conversion from grid indices to "real world" coordinates, or `null` if unknown.
  `static final int`
  `ORIGIN`
  A bitmask to specify the validity of the "real world" coordinates of cell at indices (0, 0, …, 0).
  `protected final double[]`
  `resolution`
  An estimation of the grid resolution, in units of the CRS axes.
  `static final int`
  `RESOLUTION`
  A bitmask to specify the validity of the grid resolution.
  `static final int`
  `TEMPORAL_EXTENT`
  A bitmask to specify the validity of the temporal period.
  `static final GridGeometry`
  `UNDEFINED`
  An "empty" grid geometry with no value defined.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  ``
  `GridGeometry(GridExtent extent, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)`
  Creates a new grid geometry from a grid extent and a mapping from cell coordinates to "real world" coordinates.
  ``
  `GridGeometry(GridExtent extent, Envelope envelope, GridOrientation orientation)`
  Creates an axis-aligned grid geometry with an extent and an envelope.
  `protected`
  `GridGeometry(GridGeometry other)`
  Creates a new grid geometry with the same values as the given grid geometry.
  ``
  `GridGeometry(GridGeometry other, GridExtent extent, MathTransform toOther)`
  Creates a new grid geometry derived from the given grid geometry with a new extent and a modified transform.
  ``
  `GridGeometry(GridGeometry lower, GridGeometry upper)`
  Creates a new grid geometry as the concatenation of the two specified grid geometries.
  ``
  `GridGeometry(PixelInCell anchor, MathTransform gridToCRS, Envelope envelope, GridRoundingMode rounding)`
  Creates a new grid geometry from a geospatial envelope and a mapping from cell coordinates to "real world" coordinates.
  ``
  `GridGeometry(Envelope envelope)`
  Creates a grid geometry with only an envelope.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `contains(GridGeometry other)`
  Returns `true` if this grid geometry contains the given grid geometry within a tolerance of ½ cell.
  `DerivedCRS`
  `createImageCRS(String name, PixelInCell anchor)`
  Creates a one-, two- or three-dimensional coordinate reference system for cell indices in the grid.
  `MathTransform`
  `createTransformTo(GridGeometry target, PixelInCell anchor)`
  Creates a transform from cell coordinates in this grid to cell coordinates in the given grid.
  `GridDerivation`
  `derive()`
  Returns an object that can be used for creating a new grid geometry derived from this grid geometry.
  `boolean`
  `equals(Object object)`
  Compares the specified object with this grid geometry for equality.
  `boolean`
  `equals(Object object, ComparisonMode mode)`
  Compares the specified object with this grid geometry for equality.
  `GridExtent`
  `extentOf(GridGeometry other, PixelInCell include, GridRoundingMode rounding)`
  Returns the coordinate range of another grid geometry in units of cells of this grid geometry.
  `CoordinateReferenceSystem`
  `getCoordinateReferenceSystem()`
  Returns the "real world" coordinate reference system.
  `final int`
  `getDimension()`
  Returns the number of dimensions of the grid.
  `Envelope`
  `getEnvelope()`
  Returns the bounding box of "real world" coordinates for this grid geometry.
  `Envelope`
  `getEnvelope(CoordinateReferenceSystem crs)`
  Returns the "real world" bounding box of this grid geometry transformed to the given CRS.
  `GridExtent`
  `getExtent()`
  Returns the valid coordinate range of a grid coverage.
  `Optional<GeographicBoundingBox>`
  `getGeographicExtent()`
  Returns the approximate latitude and longitude coordinates of the grid.
  `MathTransform`
  `getGridToCRS(PixelInCell anchor)`
  Returns the conversion from grid coordinates to "real world" coordinates.
  `LinearTransform`
  `getLinearGridToCRS(PixelInCell anchor)`
  Returns a linear approximation of the conversion from grid coordinates to "real world" coordinates.
  `double[]`
  `getOrigin()`
  Returns the "real world" coordinates of the cell at indices (0, 0, … 0).
  `double[]`
  `getResolution(boolean allowEstimates)`
  Returns an estimation of the grid resolution, in units of the coordinate reference system axes.
  `Instant[]`
  `getTemporalExtent()`
  Returns the start time and end time of coordinates of the grid.
  `int`
  `hashCode()`
  Returns a hash value for this grid geometry.
  `boolean`
  `intersects(GridGeometry other)`
  Returns `true` if this grid geometry intersects the given grid geometry.
  `boolean`
  `isConversionLinear(int... targets)`
  Indicates whether the grid to CRS conversion is linear for all the specified CRS axes.
  `boolean`
  `isDefined(int bitmask)`
  Returns `true` if all the properties specified by the argument are set.
  `GridGeometry`
  `relocate(GridExtent newExtent)`
  Returns a grid geometry with the given grid extent, which implies a new "real world" computation.
  `GridGeometry`
  `selectDimensions(int... indices)`
  Returns a grid geometry that encompass only some dimensions of this grid geometry.
  `final GridGeometry`
  `shiftGrid(long... translation)`
  Translates grid coordinates by the given number of cells without changing "real world" coordinates.
  `GridGeometry`
  `shiftGrid(long[] translation, boolean negate)`
  Translates grid coordinates by the given number of cells, optionally in the reverse direction.
  `GridGeometry`
  `shiftGridToZeros()`
  Translates the grid to lower coordinate values of zero without changing the "real world" coordinates.
  `String`
  `toString()`
  Returns a string representation of this grid geometry.
  `TreeTable`
  `toTree(Locale locale, int bitmask)`
  Returns a tree representation of some elements of this grid geometry.
  `GridGeometry`
  `upsample(int[] periods)`
  Deprecated.
  Use the version with `long` integers instead of `int`.
  `GridGeometry`
  `upsample(long... periods)`
  Creates a new grid geometry upsampled by the given number of cells along each grid dimensions.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### CRS

    public static final int CRS
    A bitmask to specify the validity of the Coordinate Reference System property.
    See Also:
      - `isDefined(int)`
      - `getCoordinateReferenceSystem()`
      - Constant Field Values

  - ### ENVELOPE

    public static final int ENVELOPE
    A bitmask to specify the validity of the geodetic envelope property.
    See Also:
      - `isDefined(int)`
      - `getEnvelope()`
      - Constant Field Values

  - ### EXTENT

    public static final int EXTENT
    A bitmask to specify the validity of the grid extent property.
    See Also:
      - `isDefined(int)`
      - `getExtent()`
      - Constant Field Values

  - ### GRID_TO_CRS

    public static final int GRID_TO_CRS
    A bitmask to specify the validity of the grid to CRS transform.
    See Also:
      - `isDefined(int)`
      - `getGridToCRS(PixelInCell)`
      - Constant Field Values

  - ### ORIGIN

    public static final int ORIGIN
    A bitmask to specify the validity of the "real world" coordinates of cell at indices (0, 0, …, 0).
    Since:
      1.5
    See Also:
      - `getOrigin()`
      - Constant Field Values

  - ### RESOLUTION

    public static final int RESOLUTION
    A bitmask to specify the validity of the grid resolution.
    See Also:
      - `isDefined(int)`
      - `getResolution(boolean)`
      - Constant Field Values

  - ### GEOGRAPHIC_EXTENT

    public static final int GEOGRAPHIC_EXTENT
    A bitmask to specify the validity of the geographic bounding box. This information can sometimes be derived from the envelope and the CRS. It is an optional element even with a complete grid geometry since the coordinate reference system is not required to have an horizontal component.
    See Also:
      - `getGeographicExtent()`
      - Constant Field Values

  - ### TEMPORAL_EXTENT

    public static final int TEMPORAL_EXTENT
    A bitmask to specify the validity of the temporal period. This information can sometimes be derived from the envelope and the CRS. It is an optional element even with a complete grid geometry since the coordinate reference system is not required to have a temporal component.
    See Also:
      - `getTemporalExtent()`
      - Constant Field Values

  - ### extent

    protected final GridExtent extent
    The valid domain of a grid coverage, or `null` if unknown. The lowest valid grid coordinate is zero for `BufferedImage`, but may be non-zero for arbitrary `RenderedImage`. A grid with 512 cells can have a minimum coordinate of 0 and maximum of 511.
    See Also:
      - `EXTENT`
      - `getExtent()`

  - ### envelope

    protected final ImmutableEnvelope envelope
    The geodetic envelope, or `null` if unknown. If non-null, this envelope is usually the grid `extent` transformed to real world coordinates. The Coordinate Reference System} (CRS) of this envelope defines the "real world" CRS of this grid geometry.
    See Also:
      - `ENVELOPE`
      - `getEnvelope()`

  - ### gridToCRS

    protected final MathTransform gridToCRS
    The conversion from grid indices to "real world" coordinates, or `null` if unknown. If non-null, the conversion shall map cell center. This conversion is usually, but not necessarily, affine.
    See Also:
      - `CRS`
      - `getGridToCRS(PixelInCell)`
      - `PixelInCell​.CELL_CENTER`

  - ### resolution

    protected final double[] resolution
    An estimation of the grid resolution, in units of the CRS axes. Computed from `gridToCRS`, eventually together with `extent`. May be `null` if unknown. If non-null, the array length is equal to the number of CRS dimensions.
    See Also:
      - `RESOLUTION`
      - `getResolution(boolean)`

  - ### UNDEFINED

    public static final GridGeometry UNDEFINED
    An "empty" grid geometry with no value defined. All getter methods invoked on this instance will cause `IncompleteGridGeometryException` to be thrown. This instance can be used as a place-holder when the grid geometry cannot be obtained.

- ## Constructor Details

  - ### GridGeometry

    protected GridGeometry(GridGeometry other)
    Creates a new grid geometry with the same values as the given grid geometry. This is a copy constructor for subclasses.
    Parameters:
      `other` - the other grid geometry to copy.

  - ### GridGeometry

    public GridGeometry(GridGeometry other, GridExtent extent, MathTransform toOther) throws TransformException
    Creates a new grid geometry derived from the given grid geometry with a new extent and a modified transform. This constructor is used for creating a grid geometry over a subregion (for example with the grid extent computed by `GridDerivation​.subgrid(Envelope, double...)`) or grid geometry for a subsampled raster.

    #### Conversion between old and new grid geometry

    If `toOther` is non-null, it defines the conversion from grid coordinates of given `extent` to grid coordinates of `other`. That transform should be a scale and a translation only, but more complex transforms are accepted. The `cornerToCRS` transform of the new grid geometry will be set to the following concatenation:

    > `this​.cornerToCRS` = `toOther` → `other​.cornerToCRS`

    The new grid geometry envelope will be computed from the new extent and transform, then clipped to the envelope of the other grid geometry. This clip is for preventing the envelope to become larger under the effect of subsampling because each cell become larger. The clip is not applied when `toOther` is `null` because in such case, we presume that the grid extent has been changed for another reason than subsampling (e.g. application of a margin, in which case we want the envelope to be expanded).
    Parameters:
      `other` - the other grid geometry to copy.
      `extent` - the new extent for the grid geometry to construct, or `null` if none.
      `toOther` - transform from this grid coordinates to `other` grid coordinates, or `null` if none.
    Throws:
      `NullPointerException` - if `extent` is `null` and the other grid geometry contains no other information.
      `TransformException` - if the math transform cannot compute the geospatial envelope from the grid extent.
    Since:
      1.2
    See Also:
      - `GridDerivation​.subgrid(Envelope, double...)`

  - ### GridGeometry

    public GridGeometry(GridExtent extent, PixelInCell anchor, MathTransform gridToCRS, CoordinateReferenceSystem crs)
    Creates a new grid geometry from a grid extent and a mapping from cell coordinates to "real world" coordinates. At least one of `extent`, `gridToCRS` or `crs` arguments shall be non-null. If `gridToCRS` is non-null, then `anchor` shall be non-null too with one of the following values:
    - `PixelInCell​.CELL_CENTER` if conversions of cell indices by `gridToCRS` give "real world" coordinates close to the center of each cell.
    - `PixelInCell​.CELL_CORNER` if conversions of cell indices by `gridToCRS` give "real world" coordinates at the corner of each cell. The cell corner is the one for which all grid indices have the smallest values (closest to negative infinity).

    #### API note

    There is no default value for `anchor` because experience shows that images shifted by ½ pixel (with pixels that may be tens of kilometres large) is a recurrent problem. We want to encourage developers to always think about wether their grid to CRS transform is mapping pixel corner or center.
    Upcoming API generalization: the `extent` type of this method may be changed to `GridEnvelope` interface in a future Apache SIS version. This is pending GeoAPI update. In addition, the `PixelInCell` code list currently defined in the `org​.opengis​.referencing​.datum` package may move in another package in a future GeoAPI version because this type is no longer defined by the ISO 19111 standard after the 2018 revision.
    Parameters:
      `extent` - the valid extent of grid coordinates, or `null` if unknown.
      `anchor` - Cell center for OGC conventions or cell corner for Java2D/JAI conventions.
      `gridToCRS` - the mapping from grid coordinates to "real world" coordinates, or `null` if unknown.
      `crs` - the coordinate reference system of the "real world" coordinates, or `null` if unknown.
    Throws:
      `NullPointerException` - if `extent`, `gridToCRS` and `crs` arguments are all null.
      `MismatchedDimensionException` - if the math transform and the CRS do not have consistent dimensions.
      `IllegalGridGeometryException` - if the math transform cannot compute the geospatial envelope or resolution from the grid extent.

  - ### GridGeometry

    public GridGeometry(PixelInCell anchor, MathTransform gridToCRS, Envelope envelope, GridRoundingMode rounding)
    Creates a new grid geometry from a geospatial envelope and a mapping from cell coordinates to "real world" coordinates. At least one of `gridToCRS` or `envelope` arguments shall be non-null. If `gridToCRS` is non-null, then `anchor` shall be non-null too with one of the values documented in the `constructor expecting a grid extent`.

    The given envelope shall encompass all cell surfaces, from the left border of leftmost cell to the right border of the rightmost cell and similarly along other axes. This constructor tries to store a geospatial envelope close to the specified envelope, but there is no guarantee that the envelope returned by `getEnvelope()` will be equal to the given envelope. The envelope stored in the new `GridGeometry` may be slightly smaller, larger or shifted because the floating point values used in geospatial envelope cannot always be mapped to the integer coordinates used in `GridExtent`. The rules for deciding whether coordinates should be rounded toward nearest integers, to floor or to ceil values are specified by the `GridRoundingMode` argument.

    Because of the uncertainties explained in above paragraph, this constructor should be used only in last resort, when the grid extent is unknown. For determinist results, developers should prefer the constructor using grid extent as much as possible. In particular, this constructor is not suitable for computing grid geometry of tiles in a tiled image, because the above-cited uncertainties may result in apparently random black lines between tiles.

    Upcoming API change: The `PixelInCell` code list currently defined in the `org​.opengis​.referencing​.datum` package may move in another package in a future GeoAPI version because this type is no longer defined by the ISO 19111 standard after the 2018 revision. This code list may be taken by ISO 19123 in a future revision.
    Parameters:
      `anchor` - Cell center for OGC conventions or cell corner for Java2D/JAI conventions.
      `gridToCRS` - the mapping from grid coordinates to "real world" coordinates, or `null` if unknown.
      `envelope` - the geospatial envelope, including its coordinate reference system if available. There is no guarantee that the envelope actually stored in the `GridGeometry` will be equal to this specified envelope.
      `rounding` - controls behavior of rounding from floating point values to integers.
    Throws:
      `IllegalGridGeometryException` - if the math transform cannot compute the grid extent or the resolution.

  - ### GridGeometry

    public GridGeometry(GridExtent extent, Envelope envelope, GridOrientation orientation)
    Creates an axis-aligned grid geometry with an extent and an envelope. This constructor can be used when the grid to CRS transform is unknown. If only the coordinate reference system is known, then the envelope coordinates can be all NaN.

    The main purpose of this constructor is to create "desired" grid geometries, for example for use in read or resample operations. For grid geometries describing preexisting data, it is safer and more flexible to use one of the constructors expecting a `MathTransform` argument.

    #### Dimension order

    The given envelope shall always declare dimensions in same order as the given extent. This constructor may reorder axes if `orientation` is `GridOrientation​.DISPLAY`, but in such case this constructor will derive a new envelope and a new CRS from the given envelope.
    Parameters:
      `extent` - the valid extent of grid coordinates, or `null` if unknown.
      `envelope` - the envelope together with CRS of the "real world" coordinates, or `null` if unknown.
      `orientation` - high-level description of desired characteristics of the `gridToCRS` transform. Ignored (can be null) if `envelope` is null.
    Throws:
      `NullPointerException` - if `extent` and `envelope` arguments are both null, or if `envelope` is non-null but `orientation` is null.
      `MismatchedDimensionException` - if the envelope does not have the same number of dimensions than the grid extent.
    Since:
      1.1
    See Also:
      - Axis-aligned object on Wikipedia

  - ### GridGeometry

    public GridGeometry(Envelope envelope)
    Creates a grid geometry with only an envelope.
    Parameters:
      `envelope` - the envelope together with CRS of the "real world" coordinates.
    Throws:
      `IllegalArgumentException` - if the envelope has no CRS and only NaN coordinate values.
    Since:
      1.4

  - ### GridGeometry

    public GridGeometry(GridGeometry lower, GridGeometry upper) throws FactoryException
    Creates a new grid geometry as the concatenation of the two specified grid geometries. The number of dimensions of the new grid geometry is the sum of the number of dimensions of the two specified grid geometries. The dimensions of the lower grid geometry are first, followed by the dimensions of the upper grid geometry.
    Parameters:
      `lower` - the grid geometry providing the lowest dimensions.
      `upper` - the grid geometry providing the highest dimensions.
    Throws:
      `IncompleteGridGeometryException` - if a property presents in one grid geometry is absent in the other.
      `IllegalArgumentException` - if the concatenation results in duplicated grid axis types.
      `FactoryException` - if the geodetic factory failed to create the compound CRS.
    Since:
      1.5
    See Also:
      - `selectDimensions(int...)`

- ## Method Details

  - ### getDimension

    public final int getDimension()
    Returns the number of dimensions of the grid. This is typically the same than the number of envelope dimensions or the number of coordinate reference system dimensions, but not necessarily.
    Returns:
      the number of grid dimensions.
    See Also:
      - `selectDimensions(int[])`
      - `GridExtent​.getDimension()`

  - ### getExtent

    public GridExtent getExtent()
    Returns the valid coordinate range of a grid coverage. The lowest valid grid coordinate is zero for `BufferedImage`, but may be non-zero for arbitrary `RenderedImage`. A grid with 512 cells can have a minimum coordinate of 0 and maximum of 511.
    Upcoming API generalization: the return type of this method may be changed to `GridEnvelope` interface in a future Apache SIS version. This is pending GeoAPI update.
    Returns:
      the valid extent of grid coordinates (never `null`).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no extent — i.e. `isDefined(EXTENT)` returned `false`.

  - ### getGridToCRS

    public MathTransform getGridToCRS(PixelInCell anchor)
    Returns the conversion from grid coordinates to "real world" coordinates. The conversion is often an affine transform, but not necessarily. Conversions from cell indices to geospatial coordinates can be performed for example as below:

        MathTransform  gridToCRS     = gridGeometry.getGridToCRS(PixelInCell.CELL_CENTER);
        DirectPosition indicesOfCell = new GeneralDirectPosition(2, 3, 4):
        DirectPosition aPixelCenter  = gridToCRS.transform(indicesOfCell, null);

    Callers must specify whether they want the "real world" coordinates of cell center or cell corner. The cell corner is the one for which all grid indices have the smallest values (closest to negative infinity). As a rule of thumb:
    - Use `PixelInCell​.CELL_CENTER` for transforming points.
    - Use `PixelInCell​.CELL_CORNER` for transforming envelopes with inclusive lower coordinates and exclusive upper coordinates.

    #### API note

    There is no default value for `anchor` because experience shows that images shifted by ½ pixel (with pixels that may be tens of kilometres large) is a recurrent problem. We want to encourage developers to always think about wether the desired grid to CRS transform shall map pixel corner or center.
    Parameters:
      `anchor` - the cell part to map (center or corner).
    Returns:
      the conversion from grid coordinates to "real world" coordinates (never `null`).
    Throws:
      `IllegalArgumentException` - if the given `anchor` is not a known code list value.
      `IncompleteGridGeometryException` - if this grid geometry has no transform — i.e. `isDefined(GRID_TO_CRS)` returned `false`.

  - ### getLinearGridToCRS

    public LinearTransform getLinearGridToCRS(PixelInCell anchor) throws TransformException
    Returns a linear approximation of the conversion from grid coordinates to "real world" coordinates. If the value returned by `getGridToCRS(PixelInCell)` is already an instance of `LinearTransform`, then it is returned as is. Otherwise this method computes the tangent of the transform at the grid extent point of interest (usually the center of the grid).
    Parameters:
      `anchor` - the cell part to map (center or corner).
    Returns:
      linear approximation of the conversion from grid coordinates to "real world" coordinates.
    Throws:
      `IllegalArgumentException` - if the given `anchor` is not a known code list value.
      `IncompleteGridGeometryException` - if this grid geometry has no transform, or if the transform is non-linear but this grid geometry has no extent.
      `TransformException` - if an error occurred while computing the tangent.
    Since:
      1.3

  - ### getCoordinateReferenceSystem

    public CoordinateReferenceSystem getCoordinateReferenceSystem()
    Returns the "real world" coordinate reference system.
    Returns:
      the coordinate reference system (never `null`).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no CRS — i.e. `isDefined(CRS)` returned `false`.

  - ### getEnvelope

    public Envelope getEnvelope()
    Returns the bounding box of "real world" coordinates for this grid geometry. This envelope is computed from the grid extent, which is transformed to the "real world" coordinate system. The initial envelope encompasses all cell surfaces, from the left border of leftmost cell to the right border of the rightmost cell and similarly along other axes. If this grid geometry is a subgrid, then the envelope is also clipped to the envelope of the original (non subsampled) grid geometry.
    Returns:
      the bounding box in "real world" coordinates (never `null`).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no envelope — i.e. `isDefined(ENVELOPE)` returned `false`.

  - ### getEnvelope

    public Envelope getEnvelope(CoordinateReferenceSystem crs) throws TransformException
    Returns the "real world" bounding box of this grid geometry transformed to the given CRS. This envelope is computed from the grid extent if available, or from the envelope otherwise.
    Parameters:
      `crs` - the desired coordinate reference system for the returned envelope.
    Returns:
      the bounding box in "real world" coordinates (never `null`).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no extent and no envelope.
      `TransformException` - if the envelope cannot be transformed to the specified CRS.
    Since:
      1.2

  - ### getGeographicExtent

    public Optional<GeographicBoundingBox> getGeographicExtent()
    Returns the approximate latitude and longitude coordinates of the grid. The prime meridian is Greenwich, but the geodetic reference frame is not necessarily WGS 84. This is computed from the envelope if the coordinate reference system contains an horizontal component such as a geographic or projected CRS.

    #### API note

    This method does not throw `IncompleteGridGeometryException` because the geographic extent may be absent even with a complete grid geometry. Grid geometries are not required to have a spatial component on Earth surface; a raster could be a vertical profile for example.
    Returns:
      the geographic bounding box in "real world" coordinates.

  - ### getTemporalExtent

    public Instant[] getTemporalExtent()
    Returns the start time and end time of coordinates of the grid. If the grid has no temporal dimension, then this method returns an empty array. If only the start time or end time is defined, then returns an array of length 1. Otherwise this method returns an array of length 2 with the start time in the first element and the end time in the last element.
    Returns:
      time range as an array of length 0 (if none), 1 or 2.

  - ### getOrigin

    public double[] getOrigin()
    Returns the "real world" coordinates of the cell at indices (0, 0, … 0). The returned coordinates map the cell corner. This method computes the origin from the "grid to CRS" transform if available. If that transform is not available, then the minimal coordinate values of the envelope are returned.
    Returns:
      the "real world" coordinates of the cell at indices (0, 0, … 0).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no origin — i.e. `isDefined(ORIGIN)` returned `false`.
    Since:
      1.5

  - ### getResolution

    public double[] getResolution(boolean allowEstimates)
    Returns an estimation of the grid resolution, in units of the coordinate reference system axes. The length of the returned array is the number of CRS dimensions, with `resolution[0]` being the resolution along the first CRS axis, `resolution[1]` the resolution along the second CRS axis, etc. Note that this axis order is not necessarily the same as grid axis order.

    If the resolution at CRS dimension i is not a constant factor (i.e. the `isConversionLinear(i)` returns `false`), then `resolution[i]` is set to one of the following values:

    - `Double​.NaN` if `allowEstimates` is `false`.
    - An arbitrary representative resolution otherwise. Current implementation computes the resolution at `grid center`, but different implementations may use alternative algorithms.
    Parameters:
      `allowEstimates` - whether to provide some values even for resolutions that are not constant factors.
    Returns:
      an estimation of the grid resolution (never `null`).
    Throws:
      `IncompleteGridGeometryException` - if this grid geometry has no resolution — i.e. `isDefined(RESOLUTION)` returned `false`.

  - ### isConversionLinear

    public boolean isConversionLinear(int... targets)
    Indicates whether the grid to CRS conversion is linear for all the specified CRS axes. The conversion from grid coordinates to real world coordinates is often linear for some dimensions, typically the horizontal ones at indices 0 and 1. But the vertical dimension (usually at index 2) is often non-linear, for example with data at 0, 5, 10, 100 and 1000 metres.
    Parameters:
      `targets` - indices of CRS axes. This is not necessarily the same as indices of grid axes.
    Returns:
      `true` if the conversion from grid coordinates to "real world" coordinates is linear for all the given CRS dimension.

  - ### isDefined

    public boolean isDefined(int bitmask)
    Returns `true` if all the properties specified by the argument are set. If this method returns `true`, then invoking the corresponding getter methods will not throw `IncompleteGridGeometryException`.
    Parameters:
      `bitmask` - any combination of `CRS`, `ENVELOPE`, `EXTENT`, `GRID_TO_CRS` and derived bit masks.
    Returns:
      `true` if all specified properties are defined (i.e. invoking the corresponding getter methods will not throw `IncompleteGridGeometryException`).
    Throws:
      `IllegalArgumentException` - if the specified bitmask is not a combination of known masks.
    See Also:
      - `getCoordinateReferenceSystem()`
      - `getEnvelope()`
      - `getExtent()`
      - `getResolution(boolean)`
      - `getGridToCRS(PixelInCell)`

  - ### derive

    public GridDerivation derive()
    Returns an object that can be used for creating a new grid geometry derived from this grid geometry. `GridDerivation` does not change the state of this `GridGeometry` but instead creates new instances as needed. Examples of modifications include clipping to a sub-area or applying a sub-sampling.

    Each `GridDerivation` instance can be used only once and should be used in a single thread. `GridDerivation` preserves the number of dimensions. For example, slicing sets the grid size to 1 in all dimensions specified by a slice point, but does not remove those dimensions from the grid geometry. For dimensionality reduction, see `selectDimensions(int[])`.

    #### Example

    For clipping this grid geometry to a sub-area, one can use:

        GridGeometry gg = ...;
        Envelope areaOfInterest = ...;
        gg = gg.derive().rounding(GridRoundingMode.ENCLOSING)
                        .subgrid(areaOfInterest).build();

    Returns:
      an object for deriving a grid geometry from `this`.

  - ### upsample

    public GridGeometry upsample(long... periods)
    Creates a new grid geometry upsampled by the given number of cells along each grid dimensions. This method multiplies low and high coordinates by the given periods, then scales the `grid to CRS` transform for compensating the grid change. The grid geometry `envelope` is preserved after upsampling.

    #### Number of arguments

    The `periods` array length should be equal to the number of grid dimensions. If the array is shorter, missing values default to 1 (i.e. samplings in unspecified dimensions are unchanged). If the array is longer, extraneous values are ignored.
    Parameters:
      `periods` - the upsampling factors for each dimension of this grid geometry.
    Returns:
      the upsampled grid geometry, or `this` is upsampling results in the same extent.
    Throws:
      `IllegalArgumentException` - if a period is not greater than zero.
    Since:
      1.5
    See Also:
      - `GridExtent​.upsample(long...)`

  - ### upsample

    @Deprecated(since="1.5") public GridGeometry upsample(int[] periods)
    Deprecated.
    Use the version with `long` integers instead of `int`. Small overviews of large images require large subsampling factors.
    Creates a new upsampled grid geometry (32-bits version). See `upsample(long...)` for details.
    Parameters:
      `periods` - the upsampling factors for each dimension of this grid geometry.
    Returns:
      the upsampled grid geometry, or `this` is upsampling results in the same extent.
    Throws:
      `IllegalArgumentException` - if a period is not greater than zero.
    Since:
      1.3

  - ### shiftGrid

    public final GridGeometry shiftGrid(long... translation)
    Translates grid coordinates by the given number of cells without changing "real world" coordinates. The returned grid has the same size than this grid, i.e. both low and high grid coordinates are displaced by the same number of cells. The "grid to CRS" transforms are adjusted accordingly in order to map to the same "real world" coordinates.

    #### Number of arguments

    The `translation` array length should be equal to the number of dimensions. If the array is shorter, missing values default to 0 (i.e. no translation in unspecified dimensions). If the array is longer, extraneous values are ignored.
    Parameters:
      `translation` - translation to apply on each grid axis in order.
    Returns:
      a grid geometry whose coordinates (both low and high ones) and the "grid to CRS" transforms have been translated by given numbers. If the given translation is a no-op (no value or only 0 ones), then this grid is returned as is.
    Throws:
      `ArithmeticException` - if the translation results in coordinates that overflow 64-bits integer.
    Since:
      1.3
    See Also:
      - `GridExtent​.translate(long...)`

  - ### shiftGrid

    public GridGeometry shiftGrid(long[] translation, boolean negate)
    Translates grid coordinates by the given number of cells, optionally in the reverse direction. Invoking this method is equivalent to invoking `shiftGrid(long...)`, except that this method use the negative values of the given translation terms if the `negate` argument is `true`.
    Parameters:
      `translation` - translation to apply on each grid axis in order. Can be an array of any length.
      `negate` - whether to use the negative values of the given translation terms.
    Returns:
      a grid geometry whose coordinates (both low and high ones) and the "grid to CRS" transforms have been translated by given numbers. If the given translation is a no-op (no value or only 0 ones), then this grid is returned as is.
    Throws:
      `ArithmeticException` - if the translation results in coordinates that overflow 64-bits integer.
    Since:
      1.5

  - ### shiftGridToZeros

    public GridGeometry shiftGridToZeros()
    Translates the grid to lower coordinate values of zero without changing the "real world" coordinates. The returned grid has the same size than this grid, i.e. both low and high grid coordinates are displaced by the same number of cells. The "grid to CRS" transforms are adjusted accordingly in order to map to the same "real world" coordinates.
    Returns:
      a grid geometry whose lower coordinates are zeros.
    Throws:
      `ArithmeticException` - if the translation results in upper coordinates that overflow 64-bits integer.
    Since:
      1.5

  - ### relocate

    public GridGeometry relocate(GridExtent newExtent) throws TransformException
    Returns a grid geometry with the given grid extent, which implies a new "real world" computation. The "grid to CRS" transforms and the resolution stay the same as this `GridGeometry`. The "real world" envelope is recomputed for the new grid extent using the "grid to CRS" transforms.

    The given extent is taken verbatim; this method does no clipping. The given extent does not need to intersect the extent of this grid geometry.

    Parameters:
      `newExtent` - extent of the grid geometry to return.
    Returns:
      grid geometry with the given extent. May be `this` if there is no change.
    Throws:
      `TransformException` - if the geospatial envelope cannot be recomputed with the new grid extent.
    Since:
      1.3

  - ### selectDimensions

    public GridGeometry selectDimensions(int... indices)
    Returns a grid geometry that encompass only some dimensions of this grid geometry. The specified dimensions will be copied into a new grid geometry if necessary. The selection is applied on grid extent dimensions; they are not necessarily the same as the envelope dimensions. The given dimensions must be in strictly ascending order without duplicated values. The number of dimensions of the sub grid geometry will be `dimensions​.length`.

    This method performs a dimensionality reduction. This method cannot be used for changing dimension order. The converse operation is the concatenation.

    Parameters:
      `indices` - the grid (not CRS) dimensions to select, in strictly increasing order.
    Returns:
      the sub-grid geometry, or `this` if the given array contains all dimensions of this grid geometry.
    Throws:
      `IndexOutOfBoundsException` - if an index is out of bounds.
    Since:
      1.3
    See Also:
      - `GridExtent​.getSubspaceDimensions(int)`
      - `GridExtent​.selectDimensions(int[])`
      - `CRS​.selectDimensions(CoordinateReferenceSystem, int[])`

  - ### createImageCRS

    public DerivedCRS createImageCRS(String name, PixelInCell anchor)
    Creates a one-, two- or three-dimensional coordinate reference system for cell indices in the grid. This method returns a CRS which is derived from the "real world" CRS or a subset of it. If the "real world" CRS is an instance of `SingleCRS`, then the derived CRS has the following properties:
    - `GeneralDerivedCRS​.getBaseCRS()` is `getCoordinateReferenceSystem()`.
    - `GeneralDerivedCRS​.getConversionFromBase()` is the inverse of `getGridToCRS(PixelInCell)`.
    Otherwise if the "real world" CRS is an instance of `CompoundCRS`, then only the first `SingleCRS` (the head) is used. This is usually (but not necessarily) the horizontal component of the spatial CRS. The result is usually two-dimensional, but 1 and 3 dimensions are also possible.

    Because of above relationship, it is possible to use the derived CRS in a chain of operations with (for example) `CRS​.findOperation(…)`.

    Parameters:
      `name` - name of the CRS to create.
      `anchor` - the cell part to map (center or corner).
    Returns:
      a derived CRS for coordinates (cell indices) associated to the grid extent.
    Throws:
      `IncompleteGridGeometryException` - if the CRS, grid extent or "grid to CRS" transform is missing.
    Since:
      1.3

  - ### createTransformTo

    public MathTransform createTransformTo(GridGeometry target, PixelInCell anchor) throws TransformException
    Creates a transform from cell coordinates in this grid to cell coordinates in the given grid. The returned transform handles change of Coordinate Reference System and wraparound axes (e.g. longitude axis crossing the ±180° meridian) if applicable.

    Note: the transform created by this method may be non-invertible.

    Parameters:
      `target` - the grid which will be the target of returned transform.
      `anchor` - `CELL_CENTER` for OGC conventions or `CELL_CORNER` for Java2D/JAI conventions.
    Returns:
      transform from cell coordinates in this grid to cell coordinates in the given grid.
    Throws:
      `IncompleteGridGeometryException` - if there is not enough information in the two grid geometries.
      `TransformException` - if the math transform cannot be created.
    Since:
      1.1

  - ### extentOf

    public GridExtent extentOf(GridGeometry other, PixelInCell include, GridRoundingMode rounding) throws TransformException
    Returns the coordinate range of another grid geometry in units of cells of this grid geometry. This method gets the transform between cell coordinates and uses it for converting the extent of the `other` grid geometry. The grid coordinates are rounded to integers in a way specified by the `GridRoundingMode` argument. The result does not need to be contained or to intersect the extent of this grid geometry.

    The `include` argument specifies whether to transform cell corners or cell centers:

    - With `CELL_CENTER`, the returned extent contains the cell centers of `other`.
    - With `CELL_CORNER`, the returned extent contains the cell corners of `other`. It includes both lower and upper corners, thus covering the full cell areas.

    An extent of cell centers may be smaller than an extent of cell areas by a size, on each border, of ½ of the size of the cells of `other`.

    Note that if the transformation involves, for example, a rotation or a map projection, then the returned extent may encompass more cells than the real extent of `other`. See envelope transformations for more information.

    Parameters:
      `other` - the other grid geometry from which to get the extent in units of this grid geometry.
      `include` - `CELL_CENTER` for an extent containing cell centers, or `CELL_CORNER` for an extent containing all cell corners (i.e. full areas).
      `rounding` - whether to round grid coordinates to nearest, enclosing or contained bounds.
    Returns:
      the extent of the other grid geometry in cell units of this grid geometry.
    Throws:
      `IncompleteGridGeometryException` - if there is not enough information in the two grid geometries.
      `TransformException` - if the grid extent cannot be transformed to the units of this grid geometry.
    Since:
      1.5

  - ### intersects

    public boolean intersects(GridGeometry other)
    Returns `true` if this grid geometry intersects the given grid geometry. This method compares the coordinates of the two grid extents when possible, or between the two envelopes otherwise (fallback). This method may conservatively return `true` if an accurate answer would be expensive to compute. Therefore, a return value of `true` is not a guarantee that the two grids really intersect. However, a return value of `false` guarantees that the two grids do not intersect.

    The comparison is performed in units of this grid geometry by converting the other grid if necessary. Consequently, if the CRS and "grid to CRS" transform are not the same in the two grids, then this method may not be symmetric. In other words, it is not guaranteed that `A​.intersects(B) = B​.intersects(A)` for all (A, B) pairs.

    Parameters:
      `other` - the other grid geometry to test for intersection.
    Returns:
      whether the other grid geometry intersects or may intersect this grid geometry.
    Throws:
      `IncompleteGridGeometryException` - if there is not enough information in the two grid geometries.
    Since:
      1.5
    See Also:
      - `GridExtent​.intersects(GridExtent)`

  - ### contains

    public boolean contains(GridGeometry other)
    Returns `true` if this grid geometry contains the given grid geometry within a tolerance of ½ cell. This method compares the coordinates of the two grid extents when possible, or between the two envelopes otherwise (fallback). The comparison is exact if the two grids use the same CRS and "grid to CRS". Otherwise, a coordinate transformations may be applied with the following approximations:
    - The comparison is between extents containing cell centers. Because the `other` extent may be smaller compared to an extent computed over cell areas, this approach introduces a tolerance of ½ cell in units of the `other` grid.
    - Cell coordinates are rounded to nearest integers. This approach adds another tolerance of ½ cell in units of `this` grid.
    - If the coordinate transformation between the two grids is non-linear or produces a rotation, the transformed extent of `other` may contain more cells that the reality. In such cases, this method may return `false` even if a more extensive test would have returned `true`.
    This method may conservatively return `false` if an accurate answer would be too expensive (because of the last point in above list), or if the coordinates cannot be transformed.

    #### Usage

    This method behavior is well defined when the two grids are members of the same image mosaic or pyramid: same CRS together with "grid to CRS" transforms that differ only by scale and translation factors with integer values. For other cases, this method should be considered as merely a hint because of above approximations.
    Parameters:
      `other` - the other grid geometry to test for inclusion.
    Returns:
      whether the other grid geometry is contained in this grid geometry.
    Throws:
      `IncompleteGridGeometryException` - if there is not enough information in the two grid geometries.
    Since:
      1.5
    See Also:
      - `GridExtent​.contains(GridExtent)`

  - ### equals

    public boolean equals(Object object)
    Compares the specified object with this grid geometry for equality. This method delegates to `equals(object, ComparisonMode​.STRICT)`.
    Specified by:
      `equals` in interface `LenientComparable`
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the object to compare with.
    Returns:
      `true` if the given object is equal to this grid geometry.
    See Also:
      - `ComparisonMode​.STRICT`

  - ### equals

    public boolean equals(Object object, ComparisonMode mode)
    Compares the specified object with this grid geometry for equality. If the mode is `ComparisonMode​.IGNORE_METADATA` or more flexible, then the axis types are ignored.
    Specified by:
      `equals` in interface `LenientComparable`
    Parameters:
      `object` - the object to compare with this grid geometry for equality.
      `mode` - the strictness level of the comparison.
    Returns:
      `true` if the given object is equal to this grid geometry.
    Since:
      1.1
    See Also:
      - `Utilities​.deepEquals(Object, Object, ComparisonMode)`

  - ### hashCode

    public int hashCode()
    Returns a hash value for this grid geometry. This value needs not to remain consistent between different implementations of the same class.
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Returns a string representation of this grid geometry. The returned string is implementation dependent and may change in any future version. Current implementation is equivalent to a call to `toTree(Locale, int)` with at least `EXTENT`, `ENVELOPE` and `CRS` flags. Whether more flags are present or not is unspecified.
    Overrides:
      `toString` in class `Object`

  - ### toTree

    @Debug public TreeTable toTree(Locale locale, int bitmask)
    Returns a tree representation of some elements of this grid geometry. The tree representation is for debugging or logging purposes and may change in any future SIS version.
    Parameters:
      `locale` - the locale to use for textual labels.
      `bitmask` - combination of `EXTENT`, `ENVELOPE`, `CRS`, `GRID_TO_CRS`, `ORIGIN`, `RESOLUTION`, `GEOGRAPHIC_EXTENT` and `TEMPORAL_EXTENT`.
    Returns:
      a tree representation of the specified elements.