gridcoverage.java

GEo 地理操作源代码

/*$************************************************************************************************
 **
 ** $Id: GridCoverage.java,v 1.8 2004/04/28 19:40:26 desruisseaux Exp $
 **
 ** $Source: /cvsroot/geoapi/src/org/opengis/coverage/grid/GridCoverage.java,v $
 **
 ** Copyright (C) 2003 Open GIS Consortium, Inc. All Rights Reserved. http://www.opengis.org/Legal/
 **
 *************************************************************************************************/
package org.opengis.coverage.grid;

// J2SE direct dependencies
import java.awt.image.Raster;              // For Javadoc
import java.awt.image.WritableRaster;      // For Javadoc
import java.awt.image.RenderedImage;       // For Javadoc

// OpenGIS direct dependencies
import org.opengis.coverage.Coverage;


/**
 * Represent the basic implementation which provides access to grid coverage data.
 * A <code>GridCoverage</code> implementation may provide the ability to update
 * grid values.
 *
 * @UML abstract CV_GridCoverage
 * @author <A HREF="http://www.opengis.org">OpenGIS&reg; consortium</A>
 * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
 *
 * @see RenderedImage
 * @see javax.media.jai.PixelAccessor
 */
public interface GridCoverage extends Coverage {
    /**
     * Returns <code>true</code> if grid data can be edited.
     *
     * @return <code>true</code> if grid data can be edited.
     * @UML mandatory dataEditable
     */
    boolean isDataEditable();

    /**
     * Information for the packing of grid coverage values.
     *
     * @return The information for the packing of grid coverage values.
     * @UML mandatory gridPacking
     */
    GridPacking getGridPacking();

    /**
     * Information for the grid coverage geometry.
     * Grid geometry includes the valid range of grid coordinates and the georeferencing.
     *
     * @return The information for the grid coverage geometry.
     * @UML mandatory gridGeometry
     */
    GridGeometry getGridGeometry();

    /**
     * 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 <code>null</code>.
     *
     * @return The optimal size to use for each dimension when accessing grid values,
     *         or <code>null</code> if none.
     * @UML optional optimalDataBlockSizes
     */
    int[] getOptimalDataBlockSizes();

    /**
     * Number of predetermined overviews for the grid.
     *
     * @return The number of predetermined overviews for the grid.
     * @UML mandatory numOverviews
     */
    int getNumOverviews();

    /**
     * Returns the grid geometry for an overview.
     *
     * @param overviewIndex Overview index for which to retrieve grid geometry. Indices start at 0.
     * @return The grid geometry for an overview.
     * @throws IndexOutOfBoundsException if <code>overviewIndex</code> is out of bounds.
     * @UML operation getOverviewGridGeometry
     */
    GridGeometry getOverviewGridGeometry(int overviewIndex) throws IndexOutOfBoundsException;

    /**
     * Returns a pre-calculated overview for a grid coverage. The overview indices are numbered
     * from 0 to <code>{@linkplain #getNumOverviews numberOverviews}-1</code>.
     * The overviews are ordered from highest (index 0) to lowest
     * (<code>{@linkplain #getNumOverviews numberOverviews}-1</code>) 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:
     *
     * <blockquote><table border=0>
     * <tr>
     *   <th align="center">1 meter GC</th> <th>&nbsp;</th>
     *   <th align="center">3 meter overview</th>
     * </tr>
     * <tr>
     *   <td valign="top"><table border=0 align="center">
     *     <tr> <th>Index&nbsp;</th>      <th>&nbsp;resolution</th>  </tr>
     *     <tr> <td align="center">0</td> <td align="center"> 3</td> </tr>
     *     <tr> <td align="center">1</td> <td align="center"> 9</td> </tr>
     *     <tr> <td align="center">2</td> <td align="center">27</td> </tr>
     *   </table></td>
     *   <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</td>
     *   <td valign="top"><table border=0 align="center">
     *     <tr> <th>Index&nbsp;</th>      <th>&nbsp;resolution</th>  </tr>
     *     <tr> <td align="center">0</td> <td align="center"> 9</td> </tr>
     *     <tr> <td align="center">1</td> <td align="center">27</td> </tr>
     *   </table></td>
     * </table></blockquote>
     *
     * @param overviewIndex Index of grid coverage overview to retrieve. Indexes start at 0.
     * @return a pre-calculated overview for a grid coverage.
     * @throws IndexOutOfBoundsException if <code>overviewIndex</code> is out of bounds.
     * @UML operation getOverview
     */
    GridCoverage getOverview(int overviewIndex) throws IndexOutOfBoundsException;

    /**
     * Returns the source data for a grid coverage.
     * If the <code>GridCoverage</code> was produced from an underlying dataset
     * (by {@link GridCoverageReader#read read(...)} for instance) the
     * {@link #getNumSources getNumSources()} method should returns
     * zero, and this method should not be called.
     *
     * If the <code>GridCoverage</code> was produced using
     * {link org.opengis.coverage.processing.GridCoverageProcessor} then it should return the source
     * grid coverage of the one used as input to <code>GridCoverageProcessor</code>.
     * In general the <code>getSource(i)</code> method is intended to return the original
     * <code>GridCoverage</code> on which it depends.
     *
     * This is intended to allow applications to establish what <code>GridCoverage</code>s
     * will be affected when others are updated, as well as to trace back to the "raw data".
     *
     * @param sourceDataIndex Source grid coverage index. Indexes start at 0.
     * @return The source data for a grid coverage.
     * @throws IndexOutOfBoundsException if <code>sourceDataIndex</code> is out of bounds.
     * @UML operation Coverage.getSource
     */
//  GridCoverage getSource(int sourceDataIndex) throws IndexOutOfBoundsException;

    /**
     * Return a sequence of boolean values for a block.
     * A value for each sample dimension will be returned.
     * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
     * except for the return type.
     *
     * @param  gridRange Grid range for block of data to be accessed.
     * @param  destination An optionally preallocated array in which to store the values,
     *         or <code>null</code> if none.
     * @return A sequence of boolean values for a given block in the coverage.
     *         If <code>destination</code> was non-null, then it is returned.
     *         Otherwise, a new array is allocated and returned.
     * @throws InvalidRangeException if <code>gridRange</code> is out of this grid range bounds.
     * @throws ArrayIndexOutOfBoundsException if the <code>destination</code> array is not null
     *         and too small to hold the output.
     * @UML operation getDataBlockAsBoolean
     *
     * @see #setDataBlock(GridRange, boolean[])
     */
    boolean[] getDataBlock(GridRange gridRange, boolean[] destination)
            throws InvalidRangeException, ArrayIndexOutOfBoundsException;

    /**
     * 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 {@link #getDataBlock(GridRange, double[])}
     * except for the return type.
     *
     * @param  gridRange Grid range for block of data to be accessed.
     * @param  destination An optionally preallocated array in which to store the values,
     *         or <code>null</code> if none.
     * @return A sequence of 8 bits values for a given block in the coverage.
     *         If <code>destination</code> was non-null, then it is returned.
     *         Otherwise, a new array is allocated and returned.
     * @throws InvalidRangeException if <code>gridRange</code> is out of this grid range bounds.
     * @throws ArrayIndexOutOfBoundsException if the <code>destination</code> array is not null
     *         and too small to hold the output.
     * @UML operation getDataBlockAsByte
     *
     * @see #setDataBlock(GridRange, byte[])
     * @see javax.media.jai.UnpackedImageData#getByteData()
     */
    byte[] getDataBlock(GridRange gridRange, byte[] destination)
            throws InvalidRangeException, ArrayIndexOutOfBoundsException;

    /**
     * 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 {@link #getDataBlock(GridRange, double[])}
     * except for the return type.
     *
     * @param  gridRange Grid range for block of data to be accessed.
     * @param  destination An optionally preallocated array in which to store the values,
     *         or <code>null</code> if none.
     * @return A sequence of 16 bits values for a given block in the coverage.
     *         If <code>destination</code> was non-null, then it is returned.
     *         Otherwise, a new array is allocated and returned.
     * @throws InvalidRangeException if <code>gridRange</code> is out of this grid range bounds.
     * @throws ArrayIndexOutOfBoundsException if the <code>destination</code> array is not null
     *         and too small to hold the output.
     * @UML operation getDataBlockAsInteger
     *
     * @see #setDataBlock(GridRange, int[])
     * @see javax.media.jai.UnpackedImageData#getShortData()
     */
    short[] getDataBlock(GridRange gridRange, short[] destination)
            throws InvalidRangeException, ArrayIndexOutOfBoundsException;

    /**
     * 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 {@link #getDataBlock(GridRange, double[])}
     * except for the return type.
     *
     * @param  gridRange Grid range for block of data to be accessed.
     * @param  destination An optionally preallocated array in which to store the values,
     *         or <code>null</code> if none.
     * @return A sequence of 32 bits values for a given block in the coverage.
     *         If <code>destination</code> was non-null, then it is returned.
     *         Otherwise, a new array is allocated and returned.
     * @throws InvalidRangeException if <code>gridRange</code> is out of this grid range bounds.
     * @throws ArrayIndexOutOfBoundsException if the <code>destination</code> array is not null
     *         and too small to hold the output.
     * @UML operation getDataBlockAsInteger
     *
     * @see #setDataBlock(GridRange, int[])
     * @see Raster#getPixels(int,int,int,int,int[])
     * @see javax.media.jai.UnpackedImageData#getIntData()
     */
    int[] getDataBlock(GridRange gridRange, int[] destination)
            throws InvalidRangeException, ArrayIndexOutOfBoundsException;

    /**
     * Return a sequence of float values for a block.
     * A value for each sample dimension will be returned.
     * The semantic is the same as {@link #getDataBlock(GridRange, double[])}
     * except for the return type.
     *
     * @param  gridRange Grid range for block of data to be accessed.
     * @param  destination An optionally preallocated array in which to store the values,
     *         or <code>null</code> if none.
     * @return A sequence of float values for a given block in the coverage.
     *         If <code>destination</code> was non-null, then it is returned.
     *         Otherwise, a new array is allocated and returned.
     * @throws InvalidRangeException if <code>gridRange</code> is out of this grid range bounds.
     * @throws ArrayIndexOutOfBoundsException if the <code>destination</code> array is not null
     *         and too small to hold the output.
     *
     * @see #setDataBlock(GridRange, float[])