    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_testing/src/org/deegree/model/coverage/Coverage.java $
    002    /*----------------------------------------------------------------------------
    003     This file originated as a part of GeoAPI.
    004
    005     GeoAPI is free software. GeoAPI may be used, modified and
    006     redistributed by anyone for any purpose requring only maintaining the
    007     copyright and license terms on the source code and derivative files.
    008     See the OGC legal page for details.
    009
    010     The copyright to the GeoAPI interfaces is held by the Open Geospatial
    011     Consortium, see http://www.opengeospatial.org/ogc/legal
    012    ----------------------------------------------------------------------------*/
    013    package org.deegree.model.coverage;
    014
    015    import java.awt.image.renderable.RenderableImage;
    016
    017    import org.deegree.model.crs.CoordinateSystem;
    018    import org.deegree.model.spatialschema.Envelope;
    019
    020    /**
    021     * Provides access to a coverage. The essential property of coverage is to be able to generate a value for any point
    022     * within its domain. How coverage is represented internally is not a concern.
    023     *
    024     * For example consider the following different internal representations of coverage:<br>
    025     * <UL>
    026     * <li>A coverage may be represented by a set of polygons which exhaustively tile a plane (that is each point on the
    027     * plane falls in precisely one polygon). The value returned by the coverage for a point is the value of an attribute of
    028     * the polygon that contains the point.</li>
    029     * <li>A coverage may be represented by a grid of values. The value returned by the coverage for a point is that of the
    030     * grid value whose location is nearest the point.</li>
    031     * <li>Coverage may be represented by a mathematical function. The value returned by the coverage for a point is just
    032     * the return value of the function when supplied the coordinates of the point as arguments.</li>
    033     * <li>Coverage may be represented by combination of these. For example, coverage may be represented by a combination of
    034     * mathematical functions valid over a set of polynomials.</LI>
    035     * </UL>
    036     *
    037     * A coverage has a corresponding {@link SampleDimension} for each sample dimension in the coverage. <br>
    038     * <br>
    039     * <STRONG>Implementation note:</STRONG><BR>
    040     * We expect that many implementations of {@link "org.opengis.coverage.grid.GridCoverage"} will want to leverage the
    041     * rich set of <A HREF="http://java.sun.com/products/java-media/jai/">Java Advanced Imaging (JAI)</A> features. For
    042     * those implementations, it is recommended (but not required) to implement the {@link javax.media.jai.PropertySource}
    043     * interface as well. In this case, implementation of {@link javax.media.jai.PropertySource} methods must be consistent
    044     * with {@link #getMetadataNames} and {@link #getMetadataValue} methods.
    045     *
    046     * @UML abstract CV_Coverage
    047     * @author <A HREF="http://www.opengis.org">OpenGIS&reg; consortium</A>
    048     * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
    049     *
    050     * @author last edited by: $Author: mschneider $
    051     *
    052     * @version $Revision: 20326 $, $Date: 2009-10-22 18:41:56 +0200 (Do, 22. Okt 2009) $
    053     *
    054     * @see RenderableImage
    055     * @see javax.media.jai.ImageFunction
    056     */
    057    public interface Coverage {
    058        /**
    059         * Specifies the coordinate reference system used when accessing a coverage or grid coverage with the
    060         * <code>evaluate(...)</code> methods. It is also the coordinate reference system of the coordinates used with the
    061         * math transform
    062         *
    063         * This coordinate reference system is usually different than coordinate system of the grid. Grid coverage can be
    064         * accessed (re-projected) with new coordinate reference system with the
    065         * {@link "org.opengis.coverage.processing.GridCoverageProcessor"} component. In this case, a new instance of a grid
    066         * coverage is created. <br>
    067         * <br>
    068         * Note: If a coverage does not have an associated coordinate reference system, the returned value will be
    069         * <code>null</code>.
    070         *
    071         * @return The coordinate reference system used when accessing a coverage or grid coverage with the
    072         *         <code>evaluate(...)</code> methods, or <code>null</code>.
    073         * @UML mandatory coordinateSystem
    074         */
    075        CoordinateSystem getCoordinateReferenceSystem();
    076
    077        /**
    078         * The bounding box for the coverage domain in {@linkplain #getCoordinateReferenceSystem coordinate reference
    079         * system} coordinates. For grid coverages, the grid cells are centered on each grid coordinate. The envelope for a
    080         * 2-D grid coverage includes the following corner positions.
    081         *
    082         * <blockquote>
    083         *
    084         * <pre>
    085         *  (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
    086         *  (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
    087         * </pre>
    088         *
    089         * </blockquote>
    090         *
    091         * If a grid coverage does not have any associated coordinate reference system, the minimum and maximum coordinate
    092         * points for the envelope will be empty sequences.
    093         *
    094         * @return The bounding box for the coverage domain in coordinate system coordinates.
    095         * @UML mandatory envelope
    096         */
    097        Envelope getEnvelope();
    098
    099        /**
    100         * The names of each dimension in the coverage. Typically these names are <var>x</var>, <var>y</var>, <var>z</var>
    101         * and <var>t</var>. The number of items in the sequence is the number of dimensions in the coverage. Grid coverages
    102         * are typically 2D (<var>x</var>, <var>y</var>) while other coverages may be 3D (<var>x</var>, <var>y</var>,
    103         * <var>z</var>) or 4D (<var>x</var>, <var>y</var>, <var>z</var>, <var>t</var>). The number of dimensions of the
    104         * coverage is the number of entries in the list of dimension names.
    105         *
    106         * @return The names of each dimension in the coverage.
    107         * @UML mandatory dimensionNames
    108         */
    109        String[] getDimensionNames();
    110
    111        /**
    112         * The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a band.
    113         *
    114         * @return The number of sample dimensions in the coverage.
    115         * @UML mandatory numSampleDimensions
    116         */
    117        int getNumSampleDimensions();
    118
    119        /**
    120         * Retrieve sample dimension information for the coverage. For a grid coverage a sample dimension is a band. The
    121         * sample dimension information include such things as description, data type of the value (bit, byte, integer...),
    122         * the no data values, minimum and maximum values and a color table if one is associated with the dimension. A
    123         * coverage must have at least one sample dimension.
    124         *
    125         * @param index
    126         *            Index for sample dimension to retrieve. Indices are numbered 0 to (<var>
    127         *            {@linkplain #getNumSampleDimensions n}</var>-1).
    128         * @return Sample dimension information for the coverage.
    129         * @throws IndexOutOfBoundsException
    130         *             if <code>index</code> is out of bounds.
    131         * @UML operation getSampleDimension
    132         */
    133        SampleDimension getSampleDimension( int index )
    134                                throws IndexOutOfBoundsException;
    135
    136        /**
    137         * Number of grid coverages which the grid coverage was derived from. This implementation specification does not
    138         * include interfaces for creating collections of coverages therefore this value will usually be one indicating an
    139         * adapted grid coverage, or zero indicating a raw grid coverage.
    140         *
    141         * @return The number of grid coverages which the grid coverage was derived from.
    142         * @UML mandatory numSource
    143         */
    144        int getNumSources();
    145
    146        /**
    147         * Returns the source data for a coverage. This is intended to allow applications to establish what
    148         * <code>Coverage</code>s will be affected when others are updated, as well as to trace back to the "raw data".
    149         *
    150         * @param sourceDataIndex
    151         *            Source coverage index. Indexes start at 0.
    152         * @return The source data for a coverage.
    153         * @throws IndexOutOfBoundsException
    154         *             if <code>sourceDataIndex</code> is out of bounds.
    155         * @UML operation getSource
    156         *
    157         * @see #getNumSources
    158         * @see "org.opengis.coverage.grid.GridCoverage#getSource"
    159         */
    160        Coverage getSource( int sourceDataIndex )
    161                                throws IndexOutOfBoundsException;
    162
    163        /**
    164         * List of metadata keywords for a coverage. If no metadata is available, the sequence will be empty.
    165         *
    166         * @return the list of metadata keywords for a coverage.
    167         * @UML mandatory metadataNames
    168         *
    169         * @see #getMetadataValue
    170         * @see javax.media.jai.PropertySource#getPropertyNames()
    171         */
    172        String[] getMetadataNames();
    173
    174        /**
    175         * Retrieve the metadata value for a given metadata name.
    176         *
    177         * @param name
    178         *            Metadata keyword for which to retrieve data.
    179         * @return the metadata value for a given metadata name.
    180         * @throws MetadataNameNotFoundException
    181         *             if there is no value for the specified metadata name.
    182         * @UML operation getMetadataValue
    183         *
    184         * @see #getMetadataNames
    185         * @see javax.media.jai.PropertySource#getProperty
    186         */
    187        String getMetadataValue( String name )
    188                                throws MetadataNameNotFoundException;
    189
    190        /**
    191         * Returns 2D view of this coverage as a renderable image. This optional operation allows interoperability with <A
    192         * HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>. If this coverage is a
    193         * {@link "org.opengis.coverage.grid.GridCoverage"} backed by a {@link java.awt.image.RenderedImage}, the underlying
    194         * image can be obtained with:
    195         *
    196         * <code>getRenderableImage(0,1).{@linkplain RenderableImage#createDefaultRendering()
    197         * createDefaultRendering()}</code>
    198         *
    199         * @param xAxis
    200         *            Dimension to use for the <var>x</var> axis.
    201         * @param yAxis
    202         *            Dimension to use for the <var>y</var> axis.
    203         * @return A 2D view of this coverage as a renderable image.
    204         * @throws UnsupportedOperationException
    205         *             if this optional operation is not supported.
    206         * @throws IndexOutOfBoundsException
    207         *             if <code>xAxis</code> or <code>yAxis</code> is out of bounds.
    208         */
    209        RenderableImage getRenderableImage( int xAxis, int yAxis )
    210                                throws UnsupportedOperationException, IndexOutOfBoundsException;
    211
    212    }