Module org.apache.sis.feature
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:

  • Field Details

    • HOMOTHETY

      public static final GridOrientation HOMOTHETY
      The grid­To­CRS 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 grid­To­CRS transform applies scales and translations with a flip of the second axis (y). This is equivalent to HOMOTHETY​.flip­Grid­Axis(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 grid­To­CRS 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 Rendered­Image. 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:

    • 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​.use­Variant­Of­CRS(Axes­Convention​.DISPLAY_ORIENTED). Grid­Geometrys created with this orientation have properties computed as below:
      • The Grid­Extent specified by user (never modified).
      • An envelope initialized to user-specified envelope (potentially modified as described below).
      • A grid­To­CRS 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 grid­To­CRS transform is amended with the same reordering (applied on columns) as for envelope.
      Below is an example of grid­To­CRS 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​.can­Reorder­Grid­Axis(true) is an alternative where grid axes get the same reordering than CRS axes. Consequently, the Grid­Extent may be different then the specified extent but the grid­To­CRS 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 Grid­Extent instance) in way that allows Rendered­Image to appear with expected orientation.
      See Also:

  • 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 flip­Grid­Axis(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:

    • 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 can­Reorder­Grid­Axis(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 Grid­Extent may be different than the specified one.
        • Otherwise Grid­Extent stay unchanged and axis order change is handled in the grid­To­CRS transform instead.

      Limitations

      Current implementation accepts only axis order changes and direction changes. The units of measurement changes are not yet supported. Consequently, Axes­Convention​.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:

    • 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 Grid­Extent may be replaced by a different extent. If false (the default), then axis order changes will be handled in the grid­To­CRS 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:
      hash­Code 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:
      to­String in class Object