Class GridOrientation

java.lang.Object
org.apache.sis.coverage.grid.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
Version:
1.1
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) final boolean
    Whether GridExtent can be rewritten with a different axis order for matching the CRS axis order specified by crsVariant.
    (package private) final AxesConvention
    If the user-specified CRS should be substituted by a variant of that CRS, the variant to use.
    static final GridOrientation
    CRS axes are reordered and oriented toward directions commonly used for displaying purpose.
    (package private) final long
    Set of grid axes to reverse, as a bit mask.
    static final GridOrientation
    The gridToCRS transform applies only scales and translations (no axis flip or swap).
    static final GridOrientation
    The gridToCRS transform applies scales and translations with a flip of the second axis (y).
    private static final long
    For cross-version compatibility.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    GridOrientation(long flippedAxes, AxesConvention crsVariant, boolean canReorderGridAxis)
    Creates a new enumeration value.
  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    flipGridAxis(int dimension)
    Reverses axis direction in the specified grid dimension.
    int
    Returns a hash code value for this grid orientation.
    Returns a string representation of this grid orientation.
    Substitutes the user-specified CRS by a variant of it, for example with different axis order.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • serialVersionUID

      private static final long serialVersionUID
      For cross-version compatibility.
      See Also:
    • 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: 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:

      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:
    • 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). GridGeometrys 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):

      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:
    • flippedAxes

      final long flippedAxes
      Set of grid axes to reverse, as a bit mask. For any dimension i, the bit at 1L << i is set to 1 if the grid axis at that dimension should be flipped. This is the argument to give in calls to GridExtent.cornerToCRS(Envelope, long, int[]).
      See Also:
    • crsVariant

      final AxesConvention crsVariant
      If the user-specified CRS should be substituted by a variant of that CRS, the variant to use. Otherwise null. If non-null, either the gridToCRS matrix may be non-diagonal or the GridExtent axes may be ordered, depending on canReorderGridAxis value.
      See Also:
    • canReorderGridAxis

      final boolean canReorderGridAxis
      Whether GridExtent can be rewritten with a different axis order for matching the CRS axis order specified by crsVariant. If false, then axis order changes will be handled in the gridToCRS transform instead.
      See Also:
  • Constructor Details

    • GridOrientation

      private GridOrientation(long flippedAxes, AxesConvention crsVariant, boolean canReorderGridAxis)
      Creates a new enumeration value.
  • 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:
    • 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:
    • 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