Interface GridCoverage

  • All Superinterfaces:
    Coverage

    @UML(identifier="CV_GridCoverage",
         specification=OGC_01004)
    public interface GridCoverage
    extends Coverage
    Represent the basic implementation which provides access to grid coverage data. A GridCoverage implementation may provide the ability to update grid values.
    Warning — this class will change
    Current API is derived from OGC Grid Coverages Implementation specification 1.0. We plan to replace it by new interfaces derived from ISO 19123 (Schema for coverage geometry and functions). Current interfaces should be considered as legacy and are included in this distribution only because they were part of GeoAPI 1.0 release. We will try to preserve as much compatibility as possible, but no migration plan has been determined yet.
    Since:
    GeoAPI 1.0
    See Also:
    RenderedImage
    • Method Detail

      • isDataEditable

        @UML(identifier="dataEditable",
             obligation=MANDATORY,
             specification=OGC_01004)
        boolean isDataEditable()
        Returns true if grid data can be edited.
        Returns:
        true if grid data can be edited.
      • getGridPacking

        @UML(identifier="gridPacking",
             obligation=MANDATORY,
             specification=OGC_01004)
        GridPacking getGridPacking()
        Information for the packing of grid coverage values.
        Returns:
        the information for the packing of grid coverage values.
      • getGridGeometry

        @UML(identifier="gridGeometry",
             obligation=MANDATORY,
             specification=OGC_01004)
        GridGeometry getGridGeometry()
        Information for the grid coverage geometry. Grid geometry includes the valid range of grid coordinates and the georeferencing.
        Returns:
        the information for the grid coverage geometry.
      • getOptimalDataBlockSizes

        @UML(identifier="optimalDataBlockSizes",
             obligation=OPTIONAL,
             specification=OGC_01004)
        int[] getOptimalDataBlockSizes()
        Optimal size to use for each dimension when accessing grid values. These values together give the optimal block size to use when retrieving grid coverage values. For example, a client application can achieve better performance for a 2-D grid coverage by reading blocks of 128 by 128 if the grid is tiled into blocks of this size. The sequence is ordered by dimension. If the implementation does not have optimal sizes, the sequence will be null.
        Returns:
        the optimal size to use for each dimension when accessing grid values, or null if none.
      • getNumOverviews

        @UML(identifier="numOverviews",
             obligation=MANDATORY,
             specification=OGC_01004)
        int getNumOverviews()
        Number of predetermined overviews for the grid.
        Returns:
        the number of predetermined overviews for the grid.
      • getOverviewGridGeometry

        @UML(identifier="getOverviewGridGeometry",
             obligation=MANDATORY,
             specification=OGC_01004)
        GridGeometry getOverviewGridGeometry​(int index)
                                      throws IndexOutOfBoundsException
        Returns the grid geometry for an overview.
        Parameters:
        index - Overview index for which to retrieve grid geometry. Indices start at 0.
        Returns:
        the grid geometry for an overview.
        Throws:
        IndexOutOfBoundsException - if overviewIndex is out of bounds.
      • getOverview

        @UML(identifier="getOverview",
             obligation=MANDATORY,
             specification=OGC_01004)
        GridCoverage getOverview​(int index)
                          throws IndexOutOfBoundsException
        Returns a pre-calculated overview for a grid coverage. The overview indices are numbered from 0 to numberOverviews-1. The overviews are ordered from highest (index 0) to lowest (numberOverviews-1) resolution. Overview grid coverages will have overviews which are the overviews for the grid coverage with lower resolution than the overview. For example, a 1 meter grid coverage with 3, 9, and 27 meter overviews will be ordered as in the left side below. The 3 meter overview will have 2 overviews as in the right side below:
        1 meter GC   3 meter overview
        Index   resolution
        0 3
        1 9
        2 27
                    
        Index   resolution
        0 9
        1 27
        Parameters:
        index - Index of grid coverage overview to retrieve. Indexes start at 0.
        Returns:
        a pre-calculated overview for a grid coverage.
        Throws:
        IndexOutOfBoundsException - if overviewIndex is out of bounds.
      • getSources

        List<GridCoverage> getSources()
        Returns the sources data for a grid coverage. If the GridCoverage was produced from an underlying dataset, this method should returns an empty list. If the GridCoverage was produced using {link org.opengis.coverage.processing.GridCoverageProcessor} then it should return the source grid coverages of the one used as input to GridCoverageProcessor. In general this method is intended to return the original GridCoverage on which it depends. This is intended to allow applications to establish what GridCoverages will be affected when others are updated, as well as to trace back to the "raw data".
        Specified by:
        getSources in interface Coverage
        Returns:
        the sources data for a grid coverage.
      • getDataBlock

        @Deprecated
        @UML(identifier="getDataBlockAsBoolean",
             obligation=MANDATORY,
             specification=OGC_01004)
        boolean[] getDataBlock​(GridRange range,
                               boolean[] destination)
                        throws InvalidRangeException,
                               ArrayIndexOutOfBoundsException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a sequence of boolean values for a block. A value for each sample dimension will be returned. The semantic is the same as getDataBlock(GridRange, double[]) except for the return type.
        Parameters:
        range - Grid range for block of data to be accessed.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of boolean values for a given block in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        setDataBlock(GridRange, boolean[])
      • getDataBlock

        @Deprecated
        @UML(identifier="getDataBlockAsByte",
             obligation=MANDATORY,
             specification=OGC_01004)
        byte[] getDataBlock​(GridRange range,
                            byte[] destination)
                     throws InvalidRangeException,
                            ArrayIndexOutOfBoundsException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a sequence of 8 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as getDataBlock(GridRange, double[]) except for the return type.
        Parameters:
        range - Grid range for block of data to be accessed.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of 8 bits values for a given block in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        setDataBlock(GridRange, byte[])
      • getDataBlock

        @Deprecated
        @UML(identifier="getDataBlockAsInteger",
             obligation=MANDATORY,
             specification=OGC_01004)
        short[] getDataBlock​(GridRange range,
                             short[] destination)
                      throws InvalidRangeException,
                             ArrayIndexOutOfBoundsException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a sequence of 16 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as getDataBlock(GridRange, double[]) except for the return type.
        Parameters:
        range - Grid range for block of data to be accessed.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of 16 bits values for a given block in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        setDataBlock(GridRange, int[])
      • getDataBlock

        @Deprecated
        @UML(identifier="getDataBlockAsInteger",
             obligation=MANDATORY,
             specification=OGC_01004)
        int[] getDataBlock​(GridRange range,
                           int[] destination)
                    throws InvalidRangeException,
                           ArrayIndexOutOfBoundsException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a sequence of 32 bits values for a block. A value for each sample dimension will be returned. The semantic is the same as getDataBlock(GridRange, double[]) except for the return type.
        Parameters:
        range - Grid range for block of data to be accessed.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of 32 bits values for a given block in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        setDataBlock(GridRange, int[]), Raster.getPixels(int,int,int,int,int[])
      • getDataBlock

        @Deprecated
        @UML(identifier="getValueBlockAsDouble",
             obligation=MANDATORY,
             specification=OGC_01004)
        double[] getDataBlock​(GridRange range,
                              double[] destination)
                       throws InvalidRangeException,
                              ArrayIndexOutOfBoundsException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a sequence of double values for a block. A value for each sample dimension will be returned. The return value is an N+1 dimensional safe-array, with dimensions (sample dimension, dimension n, dimension n-1, ... dimension 1). For 2 dimensional grid coverages, this safe array will be accessed as (sample dimension, column, row). The index values will be based from 0. The indices in the returned N dimensional safe array will need to be offset by range minimum coordinates to get equivalent grid coordinates.

        The requested grid range must satisfy the following rules for each dimension of the grid coverage:

        minimum grid coordinate <= grid range mimimun <= grid range maximum <= maximum grid coordinate
        The number of values returned will equal:
        (max₁ - min₁ + 1) * (max₂ - min₂ + 1) ... * (maxn - minn + 1) * numSampleDimensions
        Where min is the minimum ordinate in the grid range, max is the maximum ordinate in the grid range and N is the number of dimensions in the grid coverage.
        Parameters:
        range - Grid range for block of data to be accessed.
        destination - An optionally preallocated array in which to store the values, or null if none.
        Returns:
        a sequence of double values for a given block in the coverage. If destination was non-null, then it is returned. Otherwise, a new array is allocated and returned.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        ArrayIndexOutOfBoundsException - if the destination array is not null and too small to hold the output.
        See Also:
        setDataBlock(GridRange, double[]), Raster.getPixels(int,int,int,int,double[])
        Departure from OGC/ISO specification:
        OGC 01-004 defines this method as getValueBlockAsDouble(GridRange). GeoAPI adds the double[] argument for reusing pre-allocated arrays, which is consistent with usage in java.awt.image.Raster.
        Departure from OGC/ISO specification:
        Renamed getValueBlockAsDouble as getDataBlockAsDouble for consistency with all others getDataBlock... methods and setDataBlockAsDouble.
        TODO:
        Which indices vary fastest?
      • getPackedDataBlock

        @Deprecated
        @UML(identifier="getPackedDataBlock",
             obligation=MANDATORY,
             specification=OGC_01004)
        byte[] getPackedDataBlock​(GridRange range)
                           throws InvalidRangeException
        Deprecated.
        We should use some higher level construct instead (multi-dimensional array or something similar).
        Return a block of grid coverage data for all sample dimensions. A value for each sample dimension will be returned. This operation provides efficient access of the grid values. The sequencing order of the values in the sequence will follow the rules given by valueInBytePacking and bandPacking defined in GridPacking. The requested grid range must satisfy the following rules for each dimension of the grid coverage:
        minimum grid coordinate <= grid range mimimun <= grid range maximum <= maximum grid coordinate
        The sequence of bytes returned will match the data type of the dimension. For example, a grid with one 16 bit unsigned (UNSIGNED_16BITS) sample dimension will return 2 bytes for every cell in the block.

        Byte padding rules for grid values of less than 8 bits
        For 2D grid coverages, padding is to the nearest byte for the following cases:

        For PixelInterleaved For grids with multiple sample dimensions, padding occurs between pixels for each change in dimension type.
        For LineInterleaved Padding occurs at the end of each row or column (depending on the valueSequence of the grid).
        For BandSequencial Padding occurs at the end of every sample dimension.
        For grid values smaller than 8 bits, their order within each byte is given by the value defined in valueInBytePacking. For grid values bigger than 8 bits, the order of their bytes is given by the value defined in byteInValuePacking.
        Parameters:
        range - Grid range for block of data to be accessed.
        Returns:
        a block of grid coverage data for all sample dimensions.
        Throws:
        InvalidRangeException - if range is out of this grid range bounds.
        TODO:
        This operation can't be implemented efficiently in Java with a byte[] return type, since there is no way to cast an array of arbitrary type to an array of type byte[]. Even the java.nio.Buffer doesnt allow that (it allows the opposite way however).