Class GridDerivation

Object
GridDerivation
public class GridDerivation extends Object
Creates a new grid geometry derived from a base grid geometry with different extent or resolution. Grid­Derivation are created by calls to Grid­Geometry​.derive(). Properties of the desired grid geometry can be specified by calls to the following methods, in that order (each method is optional):
  1. rounding(Grid­Rounding­Mode), margin(int...) and/or chunk­Size(int...) in any order
  2. subgrid(Grid­Geometry), subgrid(Envelope, double...) or subgrid(Grid­Extent, long...)
  3. slice(Direct­Position) and/or slice­By­Ratio(double, int...)
Then the grid geometry is created by a call to build(). The get­Intersection() method can also be invoked for the Grid­Extent part without subsampling.

Multi-dimensional grids

All methods in this class preserve the number of dimensions. For example, the slice(Direct­Position) method sets the grid size to 1 in all dimensions specified by the slice point, but does not remove those dimensions from the grid geometry. For dimensionality reduction, see Grid­Geometry​.select­Dimensions(int[]).
Since:
1.0
See Also:

  • Field Details

    • base

      protected final GridGeometry base
      The base grid geometry from which to derive a new grid geometry.

  • Constructor Details

    • GridDerivation

      protected GridDerivation(GridGeometry base)
      Creates a new builder for deriving a grid geometry from the specified base.
      Parameters:
      base - the base to use as a template for deriving a new grid geometry.
      See Also:

  • Method Details

    • pointsToInclude

      public GridDerivation pointsToInclude(PixelInCell include)
      Specifies the points of a given grid extent to include in the result. This information is used when a grid extent is specified in units different than the units of the base grid cells, which may happen with subgrid(Grid­Geometry). In such case, the specified area of interest (AOI) needs to be transformed to the units of the base grid, and this property specifies what to include in the result:
      • With CELL_CENTER, the built extent contains the cell centers of the AOI.
      • With CELL_CORNER, the built extent contains the cell corners of the AOI. 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 given AOI.

      If this method is never invoked, the default value is Pixel­In­Cell​.CELL_CORNER (built grid extent covering the full cell areas of the given AOI extent). If this method is invoked too late, an Illegal­State­Exception is thrown.

      Parameters:
      include - CELL_CENTER for an extent containing cell centers, or CELL_CORNER for an extent containing all cell corners (i.e. full areas).
      Returns:
      this for method call chaining.
      Throws:
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      Since:
      1.5
      See Also:

    • rounding

      public GridDerivation rounding(GridRoundingMode mode)
      Controls behavior of rounding from floating point values to integers. This setting modifies computations performed by the following methods (it has no effect on other methods in this Grid­Derivation class): If this method is never invoked, the default value is Grid­Rounding­Mode​.NEAREST. If this method is invoked too late, an Illegal­State­Exception is thrown.
      Parameters:
      mode - the new rounding mode.
      Returns:
      this for method call chaining.
      Throws:
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.

    • clipping

      public GridDerivation clipping(GridClippingMode mode)
      Specifies whether to clip the derived grid extent to the extent of the base grid geometry. The default value is Grid­Clipping­Mode​.STRICT.
      Parameters:
      mode - whether to clip the derived grid extent.
      Returns:
      this for method call chaining.
      Throws:
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      Since:
      1.1

    • margin

      public GridDerivation margin(int... cellCounts)
      Specifies an number of cells by which to expand Grid­Extent after rounding. This setting modifies computations performed by the following methods: For each dimension i of the grid computed by above methods, the low grid coordinate is subtracted by cell­Count[i] and the high grid coordinate is increased by cell­Count[i]. This calculation is done in units of the base grid cells, i.e. before subsampling. For example if subsampling is 2, then a margin of 6 cells specified with this method will result in a margin of 3 cells in the grid extent computed by the build() method.

      Use case

      If the caller wants to apply bilinear interpolations in an image, (s)he will need 1 more pixel on each image border. If the caller wants to apply bi-cubic interpolations, (s)he will need 2 more pixels on each image border.

      Default values

      If this method is never invoked, the default value is zero for all dimensions. If this method is invoked too late, an Illegal­State­Exception is thrown. If the cell­Counts array length is shorter than the grid dimension, then zero is assumed for all missing dimensions.
      Parameters:
      cell­Counts - number of cells by which to expand the grid extent.
      Returns:
      this for method call chaining.
      Throws:
      Illegal­Argument­Exception - if a value is negative.
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      See Also:

    • chunkSize

      public GridDerivation chunkSize(int... cellCounts)
      Specifies the size of tiles or chunks in the base grid geometry. If a chunk size is specified, then the grid extent computed by build() will span an integer number of chunks. The grid coordinates (0, 0, …) locate the corner of a chunk.

      This property operates on the same methods as the margin. If both a margin and a chunk size are specified, then margins are added first and the resulting grid coordinates are rounded to chunk size. This calculation is done in units of the base grid cells, i.e. before subsampling. For example if subsampling is 2, then a tile size of 20×20 pixels specified with this method will result in a tile size of 10×10 cells in the grid extent computed by the build() method.

      If this method is never invoked, the default value is one for all dimensions. If this method is invoked too late, an Illegal­State­Exception is thrown. If the cell­Counts array length is shorter than the grid dimension, then one is assumed for all missing dimensions.

      Parameters:
      cell­Counts - number of cells in all tiles or chunks.
      Returns:
      this for method call chaining.
      Throws:
      Illegal­Argument­Exception - if a value is zero or negative.
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      Since:
      1.1

    • maximumSubsampling

      public GridDerivation maximumSubsampling(long... subsampling)
      Specifies the maximum subsampling values (inclusive) for each dimension. If a subsampling value is greater than a specified value in the corresponding dimension, the subsampling will be clamped to the specified maximal value. Setting a maximum value of 1 in a dimension is equivalent to disabling subsampling in that dimension.

      If this method is never invoked, then there is no maximum value. If this method is invoked too late, an Illegal­State­Exception is thrown. If the cell­Counts array length is shorter than the grid dimension, then all missing dimensions have no maximum value.

      Parameters:
      subsampling - maximal subsampling values (inclusive).
      Returns:
      this for method call chaining.
      Throws:
      Illegal­Argument­Exception - if a value is zero or negative.
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      Since:
      1.5

    • maximumSubsampling

      @Deprecated(since="1.5") public GridDerivation maximumSubsampling(int[] subsampling)
      Deprecated.
      Use the version with long integers instead of int. Small overviews of large images require large subsampling factors.
      Specifies the maximum subsampling values (32-bits version). See maximum­Subsampling(long...) for details.
      Parameters:
      subsampling - maximal subsampling values (inclusive).
      Returns:
      this for method call chaining.
      Since:
      1.1

    • subgrid

      public GridDerivation subgrid(GridGeometry areaOfInterest)
      Adapts the base grid for the geographic area and resolution of the given grid geometry. By default, the new grid geometry will cover the intersection of the base grid geometry and the spatiotemporal region given by area­Of­Interest envelope. Whether that intersection is clipped can be configured. Coordinate operations are applied as needed if the Coordinate Reference Systems are not the same. The new grid geometry resolution will be integer multiples of the base grid geometry resolution.

      If grid­Extent contains only an envelope, then this method delegates to subgrid(Envelope, double...). Otherwise, if grid­Extent contains only an extent, then this method delegates to subgrid(Grid­Extent, long...). Otherwise, the following information are mandatory:

      The following information are optional but recommended: Optional margin and chunk size can be specified for increasing the size of the grid extent computed by this method. For example if the caller wants to apply bilinear interpolations in an image, (s)he will need 1 more pixel on each image border. If the caller wants to apply bi-cubic interpolations, (s)he will need 2 more pixels on each image border.

      Usage

      This method can be helpful for implementation of Grid­Coverage­Resource​.read(Grid­Geometry, int...). Example: 
      class MyDataStorage extends GridCoverageResource {
    @Override
    public GridCoverage read(GridGeometry domain, int... range) throws DataStoreException {
        GridDerivation change = getGridGeometry().derive().subgrid(domain);
        GridExtent toRead = change.buildExtent();
        long[] subsampling = change.getSubsampling());
        // Do reading here.
    }
}

      Notes

      Parameters:
      area­Of­Interest - the area of interest and desired resolution as a grid geometry.
      Returns:
      this for method call chaining.
      Throws:
      Disjoint­Extent­Exception - if the given grid of interest does not intersect the grid extent.
      Incomplete­Grid­Geometry­Exception - if a mandatory property of a grid geometry is absent.
      Illegal­Grid­Geometry­Exception - if an error occurred while converting the envelope coordinates to grid coordinates.
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      See Also:

    • subgrid

      public GridDerivation subgrid(Envelope areaOfInterest, double... resolution)
      Requests a grid geometry over a sub-envelope and optionally with a coarser resolution. The given envelope does not need to be expressed in the same coordinate reference system (CRS) than the CRS of the base grid geometry. Coordinate conversions or transformations will be applied as needed. That envelope CRS may have less dimensions than the CRS of the base grid geometry, in which case grid dimensions not mapped to envelope dimensions will be returned unchanged. The target resolution, if provided, shall be in same units and same order as the given envelope axes. If the length of resolution array is less than the number of dimensions of area­Of­Interest, then no subsampling will be applied on the missing dimensions.

      Notes:

      Parameters:
      area­Of­Interest - the desired spatiotemporal region in any CRS (transformations will be applied as needed), or null for not restricting the sub-grid to a sub-area.
      resolution - the desired resolution in the same units and order than the axes of the given envelope, or null or an empty array if no subsampling is desired. The array length should be equal to the area­Of­Interest dimension, but this is not mandatory (zero or missing values mean no sub-sampling, extraneous values are ignored).
      Returns:
      this for method call chaining.
      Throws:
      Disjoint­Extent­Exception - if the given area of interest does not intersect the grid extent.
      Incomplete­Grid­Geometry­Exception - if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unless area­Of­Interest has no CRS neither, in which case the CRS are assumed the same).
      Illegal­Grid­Geometry­Exception - if an error occurred while converting the envelope coordinates to grid coordinates.
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      See Also:

    • subgrid

      public GridDerivation subgrid(GridExtent areaOfInterest, long... subsampling)
      Requests a grid geometry over a sub-region of the base grid geometry and optionally with subsampling. The given grid geometry must have the same number of dimensions than the base grid geometry. If the length of subsampling array is less than the number of dimensions, then no subsampling will be applied on the missing dimensions.

      Notes:

      Parameters:
      area­Of­Interest - the desired grid extent in units of base grid cells (i.e. ignoring subsampling), or null for not restricting the sub-grid to a sub-area.
      subsampling - the subsampling to apply on each grid dimension, or null if none. All values shall be greater than zero. If the array length is shorter than the number of dimensions, missing values are assumed to be 1.
      Returns:
      this for method call chaining.
      Throws:
      Disjoint­Extent­Exception - if the given area of interest does not intersect the grid extent.
      Incomplete­Grid­Geometry­Exception - if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unless area­Of­Interest has no CRS neither, in which case the CRS are assumed the same).
      Illegal­State­Exception - if a subgrid(…) or slice(…) method has already been invoked.
      Since:
      1.5
      See Also:

    • subgrid

      @Deprecated(since="1.5") public GridDerivation subgrid(GridExtent areaOfInterest, int[] subsampling)
      Deprecated.
      Use the version with long integers instead of int. Small overviews of large images require large subsampling factors.
      Requests a grid geometry over a sub-region (32-bits version). See subgrid(Grid­Extent, long...) for details.
      Parameters:
      area­Of­Interest - the desired grid extent in unit of base grid cell, or null.
      subsampling - the subsampling to apply on each grid dimension, or null if none.
      Returns:
      this for method call chaining.
      Since:
      1.1

    • slice

      public GridDerivation slice(DirectPosition slicePoint)
      Requests a grid geometry for a slice at the given "real world" position. The given position can be expressed in any coordinate reference system (CRS). The position should not define a coordinate for all dimensions, otherwise the slice would degenerate to a single point. Dimensions can be left unspecified either by assigning to slice­Point a CRS without those dimensions, or by assigning the NaN value to some coordinates.

      Example

      If the coordinate reference system of base grid geometry has (longitude, latitude, time) axes, then a (longitude, latitude) slice at time t can be created with one of the following two positions:

      Usage notes

      • This method can be invoked after subgrid(Envelope, double...), but not before.
      • If a non-default rounding mode is desired, it should be specified before to invoke this method.
      • This method does not reduce the number of dimensions of the grid geometry. For dimensionality reduction, see Grid­Geometry​.select­Dimensions(int[]).
      • If the given point is known to be expressed in the same CRS as the grid geometry, then the CRS of the point can be left unspecified (null). It may give a slight performance improvement by avoiding the check for coordinate transformation.
      Parameters:
      slice­Point - the coordinates where to get a slice. If no coordinate reference system is associated, this method assumes that the slice point CRS is the CRS of the base grid geometry.
      Returns:
      this for method call chaining.
      Throws:
      Incomplete­Grid­Geometry­Exception - if the base grid geometry has no extent, no "grid to CRS" transform, or no CRS (unless slice­Point has no CRS neither, in which case the CRS are assumed the same).
      Illegal­Grid­Geometry­Exception - if an error occurred while converting the point coordinates to grid coordinates.
      Point­Outside­Coverage­Exception - if the given point is outside the grid extent.

    • sliceByRatio

      public GridDerivation sliceByRatio(double sliceRatio, int... dimensionsToKeep)
      Requests a grid geometry for a slice at the given relative position. The relative position is specified by a ratio between 0 and 1 where 0 maps to low grid coordinates, 1 maps to high grid coordinates and 0.5 maps to the median position. The slicing is applied on all dimensions except the specified dimensions to keep.

      Example

      Given a n-dimensional cube, the following call creates a slice of the two first dimensions (numbered 0 and 1, typically the dimensions of x and y axes) located at the center (ratio 0.5) of all other dimensions (typically z and/or t axes): 
      gridGeometry.derive().sliceByRatio(0.5, 0, 1).build();
      Parameters:
      slice­Ratio - the ratio to apply on all grid dimensions except the ones to keep.
      dimensions­To­Keep - the grid dimension to keep unchanged.
      Returns:
      this for method call chaining.
      Throws:
      Incomplete­Grid­Geometry­Exception - if the base grid geometry has no extent.
      Index­Out­Of­Bounds­Exception - if a dimensions­To­Keep value is out of bounds.

    • build

      public GridGeometry build()
      Builds a grid geometry with the configuration specified by the other methods in this Grid­Derivation class.
      Returns:
      the modified grid geometry. May be the base grid geometry if no change apply.
      Throws:
      Illegal­Grid­Geometry­Exception - if the grid geometry cannot be computed because of arguments given to a subgrid(…) or other methods.
      See Also:

    • getIntersection

      public GridExtent getIntersection()
      Returns the extent of the modified grid geometry, ignoring subsampling or changes in resolution. This is the intersection of the base grid geometry with the (grid or geospatial) envelope given to a subgrid(…) method, expanded by the specified margin (if any) and potentially with some grid sizes set to 1 if a slice(…) method has been invoked. The returned extent is in units of the base grid cells, (i.e. subsampling is ignored).

      This method can be invoked after build() for getting additional information. It can also be invoked without build() if only this information is desired.

      Returns:
      intersection of grid geometry extents in units of base grid cells.
      Throws:
      Incomplete­Grid­Geometry­Exception - if the base grid geometry has no extent.

    • getGridTransform

      public LinearTransform getGridTransform(PixelInCell anchor)
      Returns the transform from derived grid coordinates to base grid coordinates. In the matrix representation of this transform, the scale factors on the diagonal are the subsampling values and the translation terms in the last column are the subsampling offsets.
      Returns:
      transform of grid coordinates from the derived grid to the base grid.
      Since:
      1.5
      See Also:

    • hasSubsampling

      public boolean hasSubsampling()
      Returns whether the conversion from the base grid to the derived grid contains a scale factor. A return value of false means that all the following are true: Conversely, a return value of true means that the above are false, except the subsampling offsets which may still be zero.
      Returns:
      whether the conversion from the base grid to the derived grid contains a scale factor.
      Since:
      1.5

    • getSubsampling

      public long[] getSubsampling()
      Returns the strides for accessing cells along each axis of the base grid. Those values define part of the conversion from derived grid coordinates (x, y, z) to base grid coordinates (x′, y′, z′) as below (generalize to as many dimensions as needed):
      • x′ = s₀⋅x + t₀
      • y′ = s₁⋅y + t₁
      • z′ = s₂⋅z + t₂
      This method returns the {s₀, s₁, s₂} values while get­Subsampling­Offsets() returns the {t₀, t₁, t₂} values. All subsampling values are strictly positive integers.

      This method can be invoked after build() for getting additional information. If subgrid(Grid­Extent, long...) has been invoked, then this method returns the values that were given in the subsampling argument.

      Application to iterations

      Iteration over area­Of­Interest grid coordinates with a stride Δx=1 corresponds to an iteration in base grid coordinates with a stride of Δx′=s₀, a stride Δy=1 corresponds to a stride Δy′=s₁, etc.
      Returns:
      an estimation of the strides for accessing cells along each axis of base grid.
      Throws:
      Illegal­State­Exception - if the subsampling factors are not integers. It may happen if the derived grid has been constructed by a call to subgrid(Envelope, double...).
      Since:
      1.1
      See Also:

    • getSubsamplingOffsets

      public long[] getSubsamplingOffsets()
      Returns the offsets to be subtracted from pixel coordinates before subsampling. In a conversion from derived grid to base grid coordinates (the opposite direction of subsampling), the offset is the value to add after multiplication by the subsampling factor. It may be negative.

      This method can be invoked after build() for getting additional information.

      Returns:
      conversion from the new grid to the original grid specified to the constructor.
      Throws:
      Illegal­State­Exception - if the subsampling offsets are not integers. It may happen if the derived grid has been constructed by a call to subgrid(Envelope, double...).
      Since:
      1.1
      See Also:

    • toString

      public String toString()
      Returns a string representation of this Grid­Derivation for debugging purpose. The returned string is implementation dependent and may change in any future version.
      Overrides:
      to­String in class Object
      Returns:
      a string representation of this Grid­Derivation for debugging purpose.