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