Package org.apache.sis.coverage.grid

# Class GridOrientation

Object
GridOrientation

All Implemented Interfaces:
  `Serializable`

public final class GridOrientation extends Object implements Serializable
High-level description about how a grid is orientated relative to the CRS axes. The orientation of a grid is closely related to the grid to CRS transform. For example the conversion from grid coordinates to CRS coordinates may flip the y axis (grid coordinates increasing toward down on screen), or may swap x and y axes, etc. The constants enumerated in this class cover only a few common cases where the grid is axis-aligned with the CRS.

Since:
  1.1
See Also:
  - `GridGeometry(GridExtent, Envelope, GridOrientation)`
  - Serialized Form

Defined in the `sis-feature` module

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final GridOrientation`
  `DISPLAY`
  CRS axes are reordered and oriented toward directions commonly used for displaying purpose.
  `static final GridOrientation`
  `HOMOTHETY`
  The `gridToCRS` transform applies only scales and translations (no axis flip or swap).
  `static final GridOrientation`
  `REFLECTION_Y`
  The `gridToCRS` transform applies scales and translations with a flip of the second axis (y).

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GridOrientation`
  `canReorderGridAxis(boolean enabled)`
  Specifies whether a change of CRS axis order should be accompanied by an equivalent change of grid axis order.
  `boolean`
  `equals(Object other)`
  Returns whether this object is equal to the given object.
  `GridOrientation`
  `flipGridAxis(int dimension)`
  Reverses axis direction in the specified grid dimension.
  `int`
  `hashCode()`
  Returns a hash code value for this grid orientation.
  `String`
  `toString()`
  Returns a string representation of this grid orientation.
  `GridOrientation`
  `useVariantOfCRS(AxesConvention variant)`
  Substitutes the user-specified CRS by a variant of it, for example with different axis order.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### HOMOTHETY

    public static final GridOrientation HOMOTHETY
    The `gridToCRS` transform applies only scales and translations (no axis flip or swap). Moving along the grid axis in dimension i causes a displacement along the CRS axis in the same dimension i. In matrix terms all non-zero coefficients are on the diagonal or in the translation column. For example in the three-dimensional case:

    >     ┌                ┐
    >     │ Sx  0   0   Tx │
    >     │ 0   Sy  0   Ty │
    >     │ 0   0   Sz  Tz │
    >     │ 0   0   0   1  │
    >     └                ┘

    with Sx > 0, Sy > 0 and Sz > 0.

  - ### REFLECTION_Y

    public static final GridOrientation REFLECTION_Y
    The `gridToCRS` transform applies scales and translations with a flip of the second axis (y). This is equivalent to `HOMOTHETY​.flipGridAxis(1)`; i.e. this is the same kind of conversion than `HOMOTHETY` except that the Sy term in the matrix is replaced by −Sy and the Ty term has a different value. For example in the three-dimensional case, the `gridToCRS` transform is:

    >     ┌                 ┐
    >     │ Sx  0   0   Tx  │
    >     │ 0  −Sy  0   Ty′ │
    >     │ 0   0   Sz  Tz  │
    >     │ 0   0   0   1   │
    >     └                 ┘

    #### When to use

    `REFLECTION_Y` is commonly used when the grid is a `RenderedImage`. By contrast, an `HOMOTHETY` transform often results in y axis oriented toward up, instead of down as commonly expected with rendered images. This `REFLECTION_Y` value matches the common usage for grids backed by images.
    See Also:
      - `flipGridAxis(int)`

  - ### DISPLAY

    public static final GridOrientation DISPLAY
    CRS axes are reordered and oriented toward directions commonly used for displaying purpose. This is equivalent to `REFLECTION_Y​.useVariantOfCRS(AxesConvention​.DISPLAY_ORIENTED)`. `GridGeometry`s created with this orientation have properties computed as below:
    - The `GridExtent` specified by user (never modified).
    - An envelope initialized to user-specified envelope (potentially modified as described below).
    - A `gridToCRS` initialized to `REFLECTION_Y` (potentially modified as described below).
    - The display oriented variant of the CRS specified by user.
    - If above CRS variant is same as user-specified CRS, we are done. Otherwise:
      - Envelope dimensions are reordered to match axis order in above CRS variant Those changes are applied on a copy of user-specified envelope.
      - The `gridToCRS` transform is amended with the same reordering (applied on columns) as for envelope.
    Below is an example of `gridToCRS` transform obtained when the display-oriented CRS variant is different than the user-specified CRS (if those CRSs are equal, then the transform is rather like the one shown in `REFLECTION_Y`):

    >     ┌                  ┐
    >     │  0   Sx  0   Tx  │
    >     │ −Sy  0   0   Ty′ │
    >     │  0   0   Sz  Tz  │
    >     │  0   0   0   1   │
    >     └                  ┘

    #### When to use

    This orientation can be used for deriving a coordinate reference system with the (longitude, latitude) or (x,y) axis order, but without altering grid axes order.

    #### Alternative

    `DISPLAY​.canReorderGridAxis(true)` is an alternative where grid axes get the same reordering than CRS axes. Consequently the `GridExtent` may be different then the specified extent but the `gridToCRS` transform always has the form shown in `REFLECTION_Y`. This alternative can be used for deriving a coordinate reference system with the (longitude, latitude) or (x,y) axis order, and modify grid cell layout (i.e. replace the `GridExtent` instance) in way that allows `RenderedImage` to appear with expected orientation.
    See Also:
      - `useVariantOfCRS(AxesConvention)`
      - `AxesConvention​.DISPLAY_ORIENTED`

- ## Method Details

  - ### flipGridAxis

    public GridOrientation flipGridAxis(int dimension)
    Reverses axis direction in the specified grid dimension. For example if grid indices are (column, row), then `flipGridAxis(1)` will reverse the direction of rows axis. Invoking this method a second time for the same dimension will cancel the flipping.
    Parameters:
      `dimension` - index of the dimension in the grid on which to apply direction reversal.
    Returns:
      a grid orientation equals to this one except for the axis flip in specified dimension.
    See Also:
      - `REFLECTION_Y`
      - `GridCoverageBuilder​.flipGridAxis(int)`

  - ### useVariantOfCRS

    public GridOrientation useVariantOfCRS(AxesConvention variant)
    Substitutes the user-specified CRS by a variant of it, for example with different axis order. If the CRS axis order changed as a result of this substitution, then:
    - Order of envelope coordinates are changed accordingly.
    - CRS axis order change is mapped to the grid in one of the following ways:
      - If `canReorderGridAxis(true)` has been invoked, then the same change is applied on grid axis order. Consequently grid axes and CRS axes stay in the same order, but the resulting `GridExtent` may be different than the specified one.
      - Otherwise `GridExtent` stay unchanged and axis order change is handled in the `gridToCRS` transform instead.

    #### Limitations

    Current implementation accepts only axis order changes and direction changes. The units of measurement changes are not yet supported. Consequently `AxesConvention​.NORMALIZED` is not accepted.
    Parameters:
      `variant` - the kind of substitution to apply on CRS, or `null` if none.
    Returns:
      a grid orientation equals to this one except that it uses the specified CRS variant.
    See Also:
      - `DISPLAY`

  - ### canReorderGridAxis

    public GridOrientation canReorderGridAxis(boolean enabled)
    Specifies whether a change of CRS axis order should be accompanied by an equivalent change of grid axis order. A value of `true` implies that user-specified `GridExtent` may be replaced by a different extent. If `false` (the default), then axis order changes will be handled in the `gridToCRS` transform instead.
    Parameters:
      `enabled` - whether changes of CRS axis order should be reflected by changes of grid axis order.
    Returns:
      a grid orientation equals to this one except that it has the specified flag.

  - ### equals

    public boolean equals(Object other)
    Returns whether this object is equal to the given object.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `other` - the other object to compare with this object.
    Returns:
      whether the two objects are equal.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this grid orientation.
    Overrides:
      `hashCode` in class `Object`

  - ### toString

    public String toString()
    Returns a string representation of this grid orientation. This is for debugging purpose and may change in any future version.
    Overrides:
      `toString` in class `Object`