001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/branches/2.2_testing/src/org/deegree/model/coverage/Coverage.java $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001-2008 by:
006 EXSE, Department of Geography, University of Bonn
007 http://www.giub.uni-bonn.de/deegree/
008 lat/lon GmbH
009 http://www.lat-lon.de
010
011 This library is free software; you can redistribute it and/or
012 modify it under the terms of the GNU Lesser General Public
013 License as published by the Free Software Foundation; either
014 version 2.1 of the License, or (at your option) any later version.
015
016 This library is distributed in the hope that it will be useful,
017 but WITHOUT ANY WARRANTY; without even the implied warranty of
018 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019 Lesser General Public License for more details.
020
021 You should have received a copy of the GNU Lesser General Public
022 License along with this library; if not, write to the Free Software
023 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024
025 Contact:
026
027 Andreas Poth
028 lat/lon GmbH
029 Aennchenstr. 19
030 53115 Bonn
031 Germany
032 E-Mail: poth@lat-lon.de
033
034 Prof. Dr. Klaus Greve
035 Department of Geography
036 University of Bonn
037 Meckenheimer Allee 166
038 53115 Bonn
039 Germany
040 E-Mail: greve@giub.uni-bonn.de
041
042
043 ---------------------------------------------------------------------------*/
044 package org.deegree.model.coverage;
045
046 import java.awt.image.renderable.RenderableImage;
047
048 import org.deegree.model.crs.CoordinateSystem;
049 import org.opengis.pt.PT_Envelope;
050
051 /**
052 * Provides access to a coverage. The essential property of coverage is to be able to generate a
053 * value for any point within its domain. How coverage is represented internally is not a concern.
054 *
055 * For example consider the following different internal representations of coverage:<br>
056 * <UL>
057 * <li>A coverage may be represented by a set of polygons which exhaustively tile a plane (that is
058 * each point on the plane falls in precisely one polygon). The value returned by the coverage for a
059 * point is the value of an attribute of the polygon that contains the point.</li>
060 * <li>A coverage may be represented by a grid of values. The value returned by the coverage for a
061 * point is that of the grid value whose location is nearest the point.</li>
062 * <li>Coverage may be represented by a mathematical function. The value returned by the coverage
063 * for a point is just the return value of the function when supplied the coordinates of the point
064 * as arguments.</li>
065 * <li>Coverage may be represented by combination of these. For example, coverage may be
066 * represented by a combination of mathematical functions valid over a set of polynomials.</LI>
067 * </UL>
068 *
069 * A coverage has a corresponding {@link SampleDimension} for each sample dimension in the coverage.
070 * <br>
071 * <br>
072 * <STRONG>Implementation note:</STRONG><BR>
073 * We expect that many implementations of {@link "org.opengis.coverage.grid.GridCoverage"} will want
074 * to leverage the rich set of <A HREF="http://java.sun.com/products/java-media/jai/">Java Advanced
075 * Imaging (JAI)</A> features. For those implementations, it is recommended (but not required) to
076 * implement the {@link javax.media.jai.PropertySource} interface as well. In this case,
077 * implementation of {@link javax.media.jai.PropertySource} methods must be consistent with
078 * {@link #getMetadataNames} and {@link #getMetadataValue} methods.
079 *
080 * @UML abstract CV_Coverage
081 * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
082 * @version <A HREF="http://www.opengis.org/docs/01-004.pdf">Grid Coverage specification 1.0</A>
083 *
084 * @author last edited by: $Author: apoth $
085 *
086 * @version $Revision: 9343 $, $Date: 2007-12-27 14:30:32 +0100 (Do, 27 Dez 2007) $
087 *
088 * @see RenderableImage
089 * @see javax.media.jai.ImageFunction
090 */
091 public interface Coverage {
092 /**
093 * Specifies the coordinate reference system used when accessing a coverage or grid coverage
094 * with the <code>evaluate(...)</code> methods. It is also the coordinate reference system of
095 * the coordinates used with the math transform
096 *
097 * This coordinate reference system is usually different than coordinate system of the grid.
098 * Grid coverage can be accessed (re-projected) with new coordinate reference system with the
099 * {@link "org.opengis.coverage.processing.GridCoverageProcessor"} component. In this case, a
100 * new instance of a grid coverage is created. <br>
101 * <br>
102 * Note: If a coverage does not have an associated coordinate reference system, the returned
103 * value will be <code>null</code>.
104 *
105 * @return The coordinate reference system used when accessing a coverage or grid coverage with
106 * the <code>evaluate(...)</code> methods, or <code>null</code>.
107 * @UML mandatory coordinateSystem
108 */
109 CoordinateSystem getCoordinateReferenceSystem();
110
111 /**
112 * The bounding box for the coverage domain in
113 * {@linkplain #getCoordinateReferenceSystem coordinate reference system} coordinates. For grid
114 * coverages, the grid cells are centered on each grid coordinate. The envelope for a 2-D grid
115 * coverage includes the following corner positions.
116 *
117 * <blockquote>
118 *
119 * <pre>
120 * (Minimum row - 0.5, Minimum column - 0.5) for the minimum coordinates
121 * (Maximum row - 0.5, Maximum column - 0.5) for the maximum coordinates
122 * </pre>
123 *
124 * </blockquote>
125 *
126 * If a grid coverage does not have any associated coordinate reference system, the minimum and
127 * maximum coordinate points for the envelope will be empty sequences.
128 *
129 * @return The bounding box for the coverage domain in coordinate system coordinates.
130 * @UML mandatory envelope
131 */
132 PT_Envelope getEnvelope();
133
134 /**
135 * The names of each dimension in the coverage. Typically these names are <var>x</var>, <var>y</var>,
136 * <var>z</var> and <var>t</var>. The number of items in the sequence is the number of
137 * dimensions in the coverage. Grid coverages are typically 2D (<var>x</var>, <var>y</var>)
138 * while other coverages may be 3D (<var>x</var>, <var>y</var>, <var>z</var>) or 4D (<var>x</var>,
139 * <var>y</var>, <var>z</var>, <var>t</var>). The number of dimensions of the coverage is the
140 * number of entries in the list of dimension names.
141 *
142 * @return The names of each dimension in the coverage.
143 * @UML mandatory dimensionNames
144 */
145 String[] getDimensionNames();
146
147 /**
148 * The number of sample dimensions in the coverage. For grid coverages, a sample dimension is a
149 * band.
150 *
151 * @return The number of sample dimensions in the coverage.
152 * @UML mandatory numSampleDimensions
153 */
154 int getNumSampleDimensions();
155
156 /**
157 * Retrieve sample dimension information for the coverage. For a grid coverage a sample
158 * dimension is a band. The sample dimension information include such things as description,
159 * data type of the value (bit, byte, integer...), the no data values, minimum and maximum
160 * values and a color table if one is associated with the dimension. A coverage must have at
161 * least one sample dimension.
162 *
163 * @param index
164 * Index for sample dimension to retrieve. Indices are numbered 0 to (<var>{@linkplain #getNumSampleDimensions n}</var>-1).
165 * @return Sample dimension information for the coverage.
166 * @throws IndexOutOfBoundsException
167 * if <code>index</code> is out of bounds.
168 * @UML operation getSampleDimension
169 */
170 SampleDimension getSampleDimension( int index )
171 throws IndexOutOfBoundsException;
172
173 /**
174 * Number of grid coverages which the grid coverage was derived from. This implementation
175 * specification does not include interfaces for creating collections of coverages therefore
176 * this value will usually be one indicating an adapted grid coverage, or zero indicating a raw
177 * grid coverage.
178 *
179 * @return The number of grid coverages which the grid coverage was derived from.
180 * @UML mandatory numSource
181 */
182 int getNumSources();
183
184 /**
185 * Returns the source data for a coverage. This is intended to allow applications to establish
186 * what <code>Coverage</code>s will be affected when others are updated, as well as to trace
187 * back to the "raw data".
188 *
189 * @param sourceDataIndex
190 * Source coverage index. Indexes start at 0.
191 * @return The source data for a coverage.
192 * @throws IndexOutOfBoundsException
193 * if <code>sourceDataIndex</code> is out of bounds.
194 * @UML operation getSource
195 *
196 * @see #getNumSources
197 * @see "org.opengis.coverage.grid.GridCoverage#getSource"
198 */
199 Coverage getSource( int sourceDataIndex )
200 throws IndexOutOfBoundsException;
201
202 /**
203 * List of metadata keywords for a coverage. If no metadata is available, the sequence will be
204 * empty.
205 *
206 * @return the list of metadata keywords for a coverage.
207 * @UML mandatory metadataNames
208 *
209 * @see #getMetadataValue
210 * @see javax.media.jai.PropertySource#getPropertyNames()
211 */
212 String[] getMetadataNames();
213
214 /**
215 * Retrieve the metadata value for a given metadata name.
216 *
217 * @param name
218 * Metadata keyword for which to retrieve data.
219 * @return the metadata value for a given metadata name.
220 * @throws MetadataNameNotFoundException
221 * if there is no value for the specified metadata name.
222 * @UML operation getMetadataValue
223 *
224 * @see #getMetadataNames
225 * @see javax.media.jai.PropertySource#getProperty
226 */
227 String getMetadataValue( String name )
228 throws MetadataNameNotFoundException;
229
230 /**
231 * Returns 2D view of this coverage as a renderable image. This optional operation allows
232 * interoperability with <A HREF="http://java.sun.com/products/java-media/2D/">Java2D</A>. If
233 * this coverage is a {@link "org.opengis.coverage.grid.GridCoverage"} backed by a
234 * {@link java.awt.image.RenderedImage}, the underlying image can be obtained with:
235 *
236 * <code>getRenderableImage(0,1).{@linkplain RenderableImage#createDefaultRendering()
237 * createDefaultRendering()}</code>
238 *
239 * @param xAxis
240 * Dimension to use for the <var>x</var> axis.
241 * @param yAxis
242 * Dimension to use for the <var>y</var> axis.
243 * @return A 2D view of this coverage as a renderable image.
244 * @throws UnsupportedOperationException
245 * if this optional operation is not supported.
246 * @throws IndexOutOfBoundsException
247 * if <code>xAxis</code> or <code>yAxis</code> is out of bounds.
248 */
249 RenderableImage getRenderableImage( int xAxis, int yAxis )
250 throws UnsupportedOperationException, IndexOutOfBoundsException;
251
252 }