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.

Custom orientations

For creating a custom orientations, one of the constants defined in this class can be used as a starting point. Then, the flip­Grid­Axis(int), use­Variant­Of­CRS(Axes­Convention) or can­Reorder­Grid­Axis(boolean) methods can be invoked.
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 as 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:

    • UNKNOWN

      public static final GridOrientation UNKNOWN
      Unknown image orientation. The grid to CRS transforms inferred from this orientation will be null. All methods in this class invoked on the UNKNOWN instance will return UNKNOWN.
      Since:
      1.6

  • 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